k7/docs/guides/cli.mdx

---
title: "CLI reference"
description: "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
k7 install [-v]
```

- **-v**: verbose output

## version

Check version of installed K7 .deb package

```bash
k7 -V
```

## create

Create a sandbox from a YAML file or flags.

```bash
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
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
k7 list [-n NAMESPACE]
```
Lists sandboxes with status, readiness, restarts, age, and image.

## delete

```bash
k7 delete NAME [-n NAMESPACE]
```
Deletes one sandbox.

## delete-all

```bash
k7 delete-all [-n NAMESPACE]
```
Deletes all sandboxes in a namespace (with confirmation).

## shell

```bash
k7 shell NAME [-n NAMESPACE]
```
Opens an interactive shell in the sandbox pod.

## logs

```bash
k7 logs NAME [-n NAMESPACE] [--tail 200] [-f]
```
Shows container logs (before script and main container).

## top

```bash
k7 top [-n NAMESPACE] [--refresh-interval 1]
```
Top-like view of CPU and memory usage.

## start-api

```bash
k7 start-api 
```
Starts the API and Cloudflared tunnel via Docker Compose.

## api-status

```bash
k7 api-status
```
Shows API running state and public URL.

## get-api-endpoint

```bash
k7 get-api-endpoint
```
Prints the public URL if available.

## stop-api

```bash
k7 stop-api
```
Stops API and Cloudflared containers.

## API keys

```bash
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>