> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katakate.org/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> All k7 commands with options and examples

Use `k7 -h` for built-in help. Below are the primary commands.

## install

Install K7 components on host node(s).

```bash theme={null}
k7 install [-v]
```

* **-v**: verbose output

## version

Check version of installed K7 .deb package

```bash theme={null}
k7 -V
```

## create

Create a sandbox from a YAML file or flags.

```bash theme={null}
k7 create -f k7.yaml
# or
k7 create --name my-sb --image alpine:latest \
  --cpu 1 --memory 1Gi --storage 2Gi \
  --env-file .env --egress 10.0.0.5/32 \
  --before-script "apk add curl"
```

### YAML configuration reference

All fields map to the server-side `SandboxConfig`:

* **name** (string, required): unique sandbox name.
* **image** (string, required): container image, e.g. `alpine:latest`.
* **namespace** (string, default `default`): Kubernetes namespace.
* **env\_file** (string, optional): (absolute) path to an env file on the host node.
* **egress\_whitelist** (array of CIDR strings, optional): allowed egress IPs, e.g. `"1.1.1.1/32"` for single hosts or `"10.0.0.0/8"` for ranges.
* **limits** (object, optional): resource limits:
  * **cpu** (string): cores or millicores, e.g. `"1"` or `"500m"`.
  * **memory** (string): e.g. `"1Gi"`, `"512Mi"`.
  * **ephemeral-storage** (string): e.g. `"2Gi"`.
* **before\_script** (string, optional): shell script run once at container start.
  * Runs with open egress; readiness waits for completion when set.
* **pod\_non\_root** (boolean, optional): run Pod as non-root (UID/GID/FSGroup 65532).
* **container\_non\_root** (boolean, optional): run container as non-root (UID 65532), no privilege escalation.
* **cap\_add** (string\[], optional): add back Linux capabilities (default policy drops ALL).
* **cap\_drop** (string\[], optional): override drop policy. If omitted, `ALL` is dropped by default.

Example `k7.yaml`:

```yaml theme={null}
name: project-build
image: alpine:latest
namespace: default
egress_whitelist:
  - "10.0.0.5/32"      # Private egress proxy/gateway
limits:
  cpu: "1"
  memory: "1Gi"
  ephemeral-storage: "2Gi"
before_script: |
  # Non-root friendly example: create a working dir and print versions
  mkdir -p "$HOME/work" && cd "$HOME/work"
  echo "PATH=$PATH"
  echo "whoami: $(whoami)"
pod_non_root: false
container_non_root: false
cap_add:
  - CHOWN
```

<Warning>
  Do not whitelist public DNS resolvers (e.g., 1.1.1.1, 8.8.8.8). Doing so re-enables DNS exfiltration (UDP/TCP 53 and DoH over 443). Prefer whitelisting only your own egress proxy IP and enforce DNS/DoH policies at the proxy.

  If using package managers that require root (e.g., `apk add`, `apt-get install`) in `before_script` make sure you didn't add security policies that prevent it such as running the pod or container as non-root. Check Security & Networking section in the API reference for more.
</Warning>

## list

```bash theme={null}
k7 list [-n NAMESPACE]
```

Lists sandboxes with status, readiness, restarts, age, and image.

## delete

```bash theme={null}
k7 delete NAME [-n NAMESPACE]
```

Deletes one sandbox.

## delete-all

```bash theme={null}
k7 delete-all [-n NAMESPACE]
```

Deletes all sandboxes in a namespace (with confirmation).

## shell

```bash theme={null}
k7 shell NAME [-n NAMESPACE]
```

Opens an interactive shell in the sandbox pod.

## logs

```bash theme={null}
k7 logs NAME [-n NAMESPACE] [--tail 200] [-f]
```

Shows container logs (before script and main container).

## top

```bash theme={null}
k7 top [-n NAMESPACE] [--refresh-interval 1]
```

Top-like view of CPU and memory usage.

## start-api

```bash theme={null}
k7 start-api 
```

Starts the API and Cloudflared tunnel via Docker Compose.

## api-status

```bash theme={null}
k7 api-status
```

Shows API running state and public URL.

## get-api-endpoint

```bash theme={null}
k7 get-api-endpoint
```

Prints the public URL if available.

## stop-api

```bash theme={null}
k7 stop-api
```

Stops API and Cloudflared containers.

## API keys

```bash theme={null}
k7 generate-api-key NAME [--expires-days 365]
k7 list-api-keys
k7 revoke-api-key NAME
```

Keys are stored at `/etc/k7/api_keys.json`. Use with `X-API-Key` or `Authorization: Bearer`.

### Flag reference (create)

* **-n, --namespace**: Kubernetes namespace (default `default`).
* **-f, --file**: YAML config file (defaults to `k7.yaml` when using `k7 create`).
* **--name**: Sandbox name (when not using YAML).
* **--image**: Container image (when not using YAML).
* **--cpu**: CPU limit (e.g., `1`, `500m`).
* **--memory**: Memory limit (e.g., `1Gi`, `512Mi`).
* **--storage**: Ephemeral storage limit (e.g., `2Gi`).
* **--env-file**: Path to env file on the host node injected as a Secret.
* **--egress CIDR**: Repeatable; whitelist CIDR blocks for egress (omit to keep open; use none for full block).
* **--before-script**: Shell script to run once at start; runs with open egress before lockdown.
* **--pod-non-root / --no-pod-non-root**: Pod-level non-root defaults.
* **--container-non-root / --no-container-non-root**: Container runs as UID 65532, no privilege escalation.
* **--cap-add CAP**: Repeatable; add back Linux capabilities (default drop ALL).
* **--cap-drop CAP**: Repeatable; override default drop policy.

<Info>
  Package installs like `apk add` require root inside the container. Either leave `container_non_root` disabled for setup or prebuild an image. See Security & networking: `/api/security`.
</Info>