k8e-sandbox-skill

name: k8e-sandbox-skill description: K8E sandbox skill — execute code and shell commands in gVisor/Kata/Firecracker-isolated pods. All code execution must go through the sandbox, never on the host. Trigger when user asks to run, execute, test, try, install, analyze code or data files. user-invocable: true

K8E Sandbox

All code execution goes through k8e-sandbox-cli — never run code directly on the host. Each session is a gVisor/Kata/Firecracker-isolated pod with kernel-level egress enforcement. Mistakes can't damage the host.

Trigger keywords (English): "run this", "execute", "test it", "install X", "check if this works", "analyze this data"

Trigger keywords (中文): "帮我跑", "运行", "试试", "执行", "测试", "安装并使用", "分析这个CSV", "处理这个文件", "看看输出", "帮我算"

Pre-flight

Before any sandbox operation, check that the required environment variables are set:

if [ -z "$K8E_SANDBOX_ENDPOINT" ] || [ -z "$K8E_SANDBOX_APIKEY" ]; then
  echo "⚠ Sandbox not configured. Please provide:"
  echo "  export K8E_SANDBOX_ENDPOINT=<server-ip>:50051"
  echo "  export K8E_SANDBOX_APIKEY=<your-api-key>"
  exit 1
fi

If either variable is missing, stop immediately and ask the user:

"I need your K8E sandbox credentials to run code securely: K8E_SANDBOX_ENDPOINT — the server address (e.g. 54.116.141.251:50051) K8E_SANDBOX_APIKEY — your API key (get it from the server: k8e sandbox-apikey create my-agent)"

Do NOT proceed with any code execution until both are set.

TLS Certificate Setup (REQUIRED for remote access)

Before using the sandbox from a remote client, the server admin MUST add the public IP to the TLS certificate. Without this, every connection will fail with:

tls: failed to verify certificate: x509: certificate is valid for 127.0.0.1, ::1, ..., not <PUBLIC_IP>

Fix — on the server, add to /etc/k8e/config.yaml:

tls-san:
  - 54.116.141.251

Then restart: systemctl restart k8e

If you see the TLS certificate error above:

1. Tell the user: "The server TLS certificate does not include the public IP. Run k8e sandbox-apikey create on the server and add tls-san to /etc/k8e/config.yaml, then restart k8e."
2. Delete the local cert cache: rm -f ~/.k8e/sandbox/ca.crt
3. Retry — the CLI will use TOFU (Trust-On-First-Use) as a temporary fallback.

Environment

Download the platform-specific binary (~44MB) from GitHub Releases.

# Download and make executable
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# On the K8E server node, auto-discovery works automatically
./k8e-sandbox-cli-linux-amd64 run "echo hello"

# From a remote client, set the gateway endpoint and API key
# (Get the API key from the server: k8e sandbox-apikey create my-agent)
export K8E_SANDBOX_ENDPOINT=<server-ip>:50051
export K8E_SANDBOX_APIKEY=k8e-abc123...
./k8e-sandbox-cli-linux-amd64 run "echo hello"

Command Reference

Run details

k8e-sandbox-cli run <code> [--lang python|bash|node|ts] [--session-id <id>] [--tenant <id>] [--timeout <seconds>] [--raw]

Code source: argument > stdin. Language default: bash.

Mode table

Session lifecycle

Auto-sessions persist across run calls within the same process. Use --tenant to persist across process restarts. Use manual mode when you need custom runtime or egress settings.

Egress rules

Default allowed hosts (kernel-level Cilium eBPF enforcement): pypi.org, files.pythonhosted.org, registry.npmjs.org, github.com, raw.githubusercontent.com

Override with --allowed-hosts on create. Everything else blocked.

Typical Scenarios

Scenario 1: Quick code execution (most common)

→ k8e-sandbox-cli run "print('hello')" --lang python
→ parse JSON output, display stdout to user

No session management needed. CLI auto-creates and reuses.

Scenario 2: Install package then use it

1. k8e-sandbox-cli run "pip install pandas" --lang bash
2. k8e-sandbox-cli run "python3 -c 'import pandas; print(pandas.__version__)'" --lang bash

Same auto-session reused across both calls.

Scenario 3: Write file, execute, read results

1. k8e-sandbox-cli write $SID /workspace/analyze.py <<'PYEOF'
   import pandas as pd
   df = pd.read_csv('/workspace/data.csv')
   print(df.describe())
   PYEOF

2. echo "name,value\na,1\nb,2" | k8e-sandbox-cli write $SID /workspace/data.csv

3. k8e-sandbox-cli run "python3 /workspace/analyze.py" --session-id $SID

4. k8e-sandbox-cli read $SID /workspace/result.json --raw | jq .

Scenario 4: Custom egress + explicit session

1. SID=$(k8e-sandbox-cli create --runtime gvisor --allowed-hosts pypi.org,api.example.com | jq -r .session_id)
2. k8e-sandbox-cli run "curl -s https://api.example.com/data" --session-id $SID
3. k8e-sandbox-cli destroy $SID

Scenario 5: Parallel sub-agents

1. SUB1=$(k8e-sandbox-cli subagent $PARENT | jq -r .session_id)
2. SUB2=$(k8e-sandbox-cli subagent $PARENT | jq -r .session_id)
3. k8e-sandbox-cli run "python3 task_a.py" --session-id $SUB1 --raw &
4. k8e-sandbox-cli run "python3 task_b.py" --session-id $SUB2 --raw &
5. wait

Sub-agents share parent /workspace PVC, communicate via files. Max depth 1.

Scenario 6: Human approval for destructive actions

1. k8e-sandbox-cli confirm $SID "delete /workspace/production-data"  →  blocks, outputs approval prompt to stderr
2. Show the stderr output to user — they copy the approve command
3. Command returns {"approved": true} on success

For non-blocking registration: add --no-wait, get approval_id, call k8e-sandbox-cli approve $AID later.

Error reference

JSON error output format:

{"error":"description","detail":"specific cause"}
{"ok":false,"error":"reason"}

Isolated runtimes

Use --runtime firecracker only when /dev/kvm is available. gVisor is the recommended default — no KVM required.

Your role

Do:

• Run ALL code through k8e-sandbox-cli run, never on host
• Use --lang python for .py code, --lang bash for shell commands
• Use --raw for long-running output (training, streaming)
• Use jq to parse JSON output: k8e-sandbox-cli run "..." | jq -r .stdout
• Auto-manage sessions (default mode) unless custom settings needed
• Show stderr from confirm to user verbatim

Don't:

• Never run python3, node, pip, npm, curl directly on host
• Never use k8e-sandbox-cli run with sudo
• Don't create sessions manually when auto-mode works