Sandbox CLI

k8e-sandbox-cli is a standalone binary (~44MB) that gives AI agents direct access to K8E sandbox infrastructure — no server install needed.

AI Agent (claude code / codex / pi)
    │  shell command
    ▼
k8e-sandbox-cli run "print('hello')" --lang python
    │  gRPC (TLS)
    ▼
sandbox-grpc-gateway:50051
    │
    ▼
Isolated Pod (gVisor / Kata / Firecracker)

Install the Skill

Three steps: give the server its public name → create an API key → connect from your agent machine.

1. Tell the server the name clients will dial (remote / cloud hosts only)

The sandbox gateway certificate (:50051, mTLS) is generated from the host's interface addresses — on AWS those are private VPC IPs, so a client dialing the public name fails the TLS handshake. Set the public name (KIP-22) in whichever way suits your setup:

# /etc/k8e/config.yaml  (server daemon config — same keys as CLI flags)
sandbox-advertise-hostname: sandbox.example.com   # or the Elastic IP, e.g. 203.0.113.10

# equivalent one-shot flag
k8e-server --sandbox-advertise-hostname sandbox.example.com

# legacy env fallback — inject into the k8e-server process (e.g. systemd),
# NOT a login shell; merged alongside the flag above
# K8E_SANDBOX_ADVERTISED_HOSTNAME=sandbox.example.com

A bare DNS name or a bare IP — nothing else. Schemes (https://…), ports (host:50051), paths and whitespace are rejected: k8e-server refuses to start with invalid --sandbox-advertise-hostname: …. A value that parses as an IP lands in the cert's IP SANs, anything else in its DNS SANs. tls-san in /etc/k8e/config.yaml is not the knob for this — it only shapes the kube-apiserver serving cert.

Restart k8e-server — the gateway certificate regenerates automatically when the SAN set changes, so the new name works on the next connect. No manual deletion of /var/lib/k8e/server/tls/sandbox-server.{crt,key}.

2. Create an API key on the server (default TTL 30 days)

k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "e2b_key":"e2b_849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "ttl_days":30,"created_at":"...","expires_at":"..."}
# then, when the server's public name is known:
# mcp client config:
# {"url":"https://sandbox.example.com/mcp","headers":{"Authorization":"Bearer e2b_849a5302e66f98d1…"}}

# Optional: longer or non-expiring bootstrap keys
# k8e sandbox-apikey create my-agent --ttl 90d      # also: 720h, or a plain number of days
# k8e sandbox-apikey create my-agent --ttl never   # also: none / 0

Pass key (bare hex) to connect --apikey. Hand e2b_key to the official e2b SDKs — they require the e2b_ prefix and the server strips it. The mcp client config block is copy-pasteable straight into an MCP client (Claude Code, Codex); it is printed only when the server's public name is known, so a host without one simply omits it.

3. On the client, download the CLI and connect

connect authenticates over mTLS, puts k8e-sandbox-cli on PATH, remembers the gateway, and installs the /k8e-sandbox skill into your harnesses — so later commands need no --endpoint at all.

# 1. Download the platform-specific binary (~44MB)
#    pick your platform: linux-amd64 | linux-arm64 | darwin-amd64 | darwin-arm64 | windows-amd64.exe
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# 2. Symlink the plain command name to the downloaded file (do not rename)
#    optionally move both into a PATH dir, e.g. ~/.local/bin/
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli

# 3. Connect: mTLS auth + verify the gateway + install the /k8e-sandbox skill
#    (Claude / Codex / Pi / dsh; --agent picks the target, default auto-detect)
#    Note: --endpoint and --apikey are global flags, placed before the subcommand
./k8e-sandbox-cli --endpoint sandbox.example.com:50051 --apikey 849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9 connect

# Same command with the flags on the subcommand (both spellings work)
# ./k8e-sandbox-cli connect --endpoint sandbox.example.com:50051 --apikey 849a… --ca-file ./sandbox-ca.crt

# Multi-cluster: use a named profile (see Configuration below)
# ./k8e-sandbox-cli --profile prod connect --apikey 849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9

On the same machine as the server? Just run k8e-sandbox-cli connect — the CLI auto-discovers the local gateway and its certs; no API key needed.

4. Get the gateway CA onto the client

The gateway presents a private CA that your machine does not trust, so the first remote connect needs that CA. connect and login verify the gateway via system trust, a cached CA, or --ca-file.

On the server host the CLI can export it directly:

k8e-sandbox-cli tls export-ca --output ~/sandbox-ca.crt
# or to stdout:  k8e-sandbox-cli tls export-ca -

Without the CLI on the server, the same file is on disk:

sudo cat /var/lib/k8e/server/tls/sandbox-ca.crt > ~/sandbox-ca.crt

Copy it to the client machine and hand it to the first connect:

scp user@server:~/sandbox-ca.crt ./
./k8e-sandbox-cli --endpoint <server-ip>:50051 --apikey <key> \
  connect --ca-file ./sandbox-ca.crt

The CA is a public certificate, not a secret — it only proves the gateway is this gateway. The API key is the secret; the client private key never leaves the client.

tls export-ca also looks for a sandbox-matrix/sandbox-ca ConfigMap when the client has a kubeconfig — but the cluster does not publish that ConfigMap today, so the server-host path above is the one that works. If you are on the server host, k8e-sandbox-cli connect with no arguments skips all of this: it auto-discovers the local gateway and its certs.

5. Verify the whole path works

One command proves the API key, the mTLS client certificate, the gRPC gateway, the warm pool and the runtime all line up:

k8e-sandbox-cli run 'echo hello from k8e'
# → {"duration_ms":…,"exit_code":0,"session_id":"sess-…","status":"completed",
#    "stdout":"hello from k8e\n","stderr":"","…":…}

hello from k8e in stdout means you are running code inside an isolated gVisor pod. If it fails, the troubleshooting table below maps the symptom to the cause.

Platform binaries:

One binary, two names: the downloaded platform-suffixed file is the k8e-sandbox-cli command — the symlink is just a plain-name alias. All examples below use k8e-sandbox-cli.

Then in your agent harness:

/k8e-sandbox <goal>            # Claude Code
$k8e-sandbox <goal>            # Codex (or pick it from /skills)
/skill:k8e-sandbox <goal>      # Pi

dsh (DeepSeek Harness) loads the same skill through its skill tool, or you can name it directly in chat — see dsh + k8e-sandbox for the plugin-mounted path.

Or ask naturally: "Run this Python snippet in a sandbox" — the skill drives k8e-sandbox-cli run.

Skill not showing up? Run k8e-sandbox-cli connect --skill-only to refresh the harness installs without dialing the gateway, then open a new agent session. k8e-sandbox-cli doctor checks binary / PATH / profile / certs / skill install (add --json for a machine-readable report, --fix to apply the safe local repairs).

Available Commands

See pkg/sandboxcli/skills/k8e-sandbox/SKILL.md for full usage, plus KIP-17 (profiles + API-key TTL) and KIP-22 (the advertise hostname above).

Examples — from one-liners to a Vue website

See Sandbox Examples — Driven by Your AI Agent for the hands-on walkthrough, where you drive everything from your agent harness (pi / Claude Code / Codex) through the /k8e-sandbox skill. This page is the raw command reference; the examples page shows the same commands being invoked by the skill on your behalf.

A quick taste of what the skill runs for you:

Quick Examples

# Shell command (default lang=bash)
k8e-sandbox-cli run "ls -la /workspace"

# TypeScript — type annotations run via tsx
k8e-sandbox-cli run "const nums: number[] = [1, 2, 3]; console.log(nums.reduce((a, b) => a + b, 0))" --lang ts

# Background exec (returns run_id immediately, then poll)
k8e-sandbox-cli run "sleep 30; echo done" --background
k8e-sandbox-cli poll <run-id>

# Tenant-based cross-process session reuse
k8e-sandbox-cli run "echo hello" --tenant my-project

# Stream long-running output
k8e-sandbox-cli run "python3 train.py" --session-id $SID --raw

# Sub-agent: child session sharing parent pod + workspace
k8e-sandbox-cli subagent <parent-sid>

# Snapshots: content-addressed save/restore
SID=$(k8e-sandbox-cli create | jq -r .session_id)
k8e-sandbox-cli run "echo work > /workspace/state.txt" --session-id $SID
k8e-sandbox-cli snapshot save $SID my-state
k8e-sandbox-cli snapshot list
# ... later, new session from the snapshot:
k8e-sandbox-cli snapshot restore my-state
# incremental restore from an existing snapshot (KIP-16 M2):
k8e-sandbox-cli snapshot restore my-state --base older-state

Expose a Service (KIP-24)

When your code starts a long-running service (web app, API server) inside the sandbox, expose it through the k8e API Gateway and get a URL you can open:

k8e-sandbox-cli run "python3 -m http.server 8080 --bind 127.0.0.1" --background
k8e-sandbox-cli expose 8080
# -> {"url":"http://<gateway>/k8e/expose/<sid>/8080/","port":8080,"session_id":"..."}
curl http://<gateway>/k8e/expose/<sid>/8080/
k8e-sandbox-cli exposed            # list live exposures
k8e-sandbox-cli unexpose 8080      # stop exposing

The URL routes through the Cilium Gateway API → the embedded e2b HTTP server → a reverse proxy to the pod — no port-forwarding, no inbound pod exposure.

Troubleshooting

Start with k8e-sandbox-cli doctor — it checks the binary, PATH, profile, certs and skill install, and prints the fix for each failure (--json for a machine-readable report, --fix to apply the safe local repairs).

Configuration & Auth

Config files (do not mix these up)

/etc/k8e/config.yaml takes the same keys as CLI flags (cobra-style flag-name: value), so anything you can pass to k8e-server you can put in the file — which is what makes sandbox-advertise-hostname survive restarts.

mTLS bootstrap

Remote connect / login uses the API key once to issue a client certificate. The private key never leaves the machine. Later RPCs use mTLS only (no API key on the wire).

First authentication verifies the gateway using system trust, a cached CA, or an administrator-provided --ca-file — obtain that CA through a trusted channel. --insecure-bootstrap bypasses server verification only when no CA is selected; it exposes the API key to server impersonation, so it is not a default step. Concurrent CLI processes serialize credential initialization and renewal.

Client certificates last 90 days and auto-renew when fewer than 30 days remain. If a server is reinstalled or the CA rotated, re-run connect with fresh credentials and the new CA — --reset-certs validates them before replacing the cached files:

k8e-sandbox-cli --endpoint sandbox.example.com:50051 --apikey <key> connect \
  --reset-certs --ca-file /path/to/trusted-new-ca.crt

Multi-cluster profiles

# ~/.k8e/sandbox/profiles.yaml  — NOT /etc/k8e/config.yaml
version: 1
current_profile: default
profiles:
  default:
    endpoint: 10.0.0.1:50051
  prod:
    endpoint: sandbox.prod.example:50051
    cert_dir: ~/.k8e/sandbox-prod
    device_name: laptop-prod

k8e-sandbox-cli --profile prod connect --apikey <64-hex key>
k8e-sandbox-cli --profile prod run 'echo hi'
# or: export K8E_SANDBOX_PROFILE=prod

connect writes the gateway it authenticated against as the default profile, so later CLI calls dial it with no --endpoint at all.

Resolution order: flags → env → profile → last-connect stamp (config.json) → defaults. The cert dir has no flag: K8E_SANDBOX_CERT_DIR → profile cert_dir → ~/.k8e/sandbox.
Env: K8E_SANDBOX_ENDPOINT, K8E_SANDBOX_APIKEY, K8E_SANDBOX_CERT_DIR, K8E_SANDBOX_PROFILE, K8E_SANDBOX_CONFIG (explicit profiles file path), K8E_SANDBOX_DEVICE_NAME, K8E_SANDBOX_SESSION_ID, K8E_SANDBOX_TENANT.

Overrides

# Authenticate only (mTLS cert; no skill install) — later commands need no --apikey
k8e-sandbox-cli --endpoint sandbox.example.com:50051 --apikey <key> login

k8e-sandbox-cli run "echo hello"

# Or via environment variables:
K8E_SANDBOX_ENDPOINT=sandbox.example.com:50051 K8E_SANDBOX_APIKEY=<key> k8e-sandbox-cli login

# Override endpoint per-command:
K8E_SANDBOX_ENDPOINT=10.0.0.2:50051 k8e-sandbox-cli run "echo hello"