Skip to main content
Use k7 -h for built-in help. Below are the primary commands.

​
install

Install K7 components on host node(s). 
k7 install [-v]
  • -v: verbose output

​
version

Check version of installed K7 .deb package 
k7 -V

​
create

Create a sandbox from a YAML file or flags. 
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: 
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
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.

​
list

k7 list [-n NAMESPACE]
Lists sandboxes with status, readiness, restarts, age, and image.

​
delete

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

​
delete-all

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

​
shell

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

​
logs

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

​
top

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

​
start-api

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

​
api-status

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

​
get-api-endpoint

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

​
stop-api

k7 stop-api
Stops API and Cloudflared containers.

​
API keys

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.
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.