Getting Started

Quick Start guide — from zero to a running agentic sandbox matrix.

Step 1 — Install K8E

curl -sfL https://k8e.sh/install.sh | sh -

The installer pulls the latest release. This guide is verified against v1.37.0-20261022-rc2 and newer — earlier releases miss fixes in the sandbox daemon that the pages below rely on (coloured command output, file watch event names).

The one-click installer installs the recommended sandbox runtime (gVisor) automatically — no KVM required.

Optional — manual sandbox runtime install (gVisor)

Install the runtime shim before K8E so it is auto-detected on first startup. gVisor is recommended — no KVM required. (These manual steps are for pre-provisioning, air-gapped hosts, or custom binary locations.)

# Official "Latest release" bundle: https://gvisor.dev/docs/user_guide/install/#latest-release
# Since the 2026-07 multi-file layout, bare runsc binaries are no longer published.
ARCH=$(uname -m)   # x86_64 on most servers, aarch64 on ARM
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}

wget ${URL}/gvisor.tar.zstd ${URL}/gvisor.tar.zstd.sha512

sha512sum -c gvisor.tar.zstd.sha512   # must print OK
sudo tar --zstd -xf gvisor.tar.zstd -C /usr/local/bin
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1 /usr/local/bin/gvisor-bin   # verify installed

No zstd on the host? The same directory ships gvisor.tar.bz2 — use sudo tar -xjf gvisor.tar.bz2 -C /usr/local/bin instead.

The bundle contains runsc, the containerd-shim-runsc-v1 shim and a gvisor-bin/ directory of sidecar binaries that runsc resolves next to its own binary. Extract the whole bundle and keep the files together — do not relocate runsc alone.

K8E detects runsc at startup and automatically injects the gVisor stanza into its containerd config (/var/lib/k8e/agent/etc/containerd/config.toml). Do not run runsc install — K8E manages its own containerd configuration.

Need stronger isolation? See Sandbox Runtime Setup for Kata Containers and Firecracker.

Step 2 — Verify Cluster

export KUBECONFIG=/etc/k8e/k8e.yaml
kubectl get nodes
kubectl get runtimeclass              # should show: gvisor
kubectl -n sandbox-matrix get pods   # Sandbox Matrix starts automatically

Step 3 — Connect a Client to the Cluster

Two different binaries are involved, and they live on different machines:

3a — On the server: name the address clients will dial, then mint a key

Clients reach the sandbox gateway at :50051 (gRPC, mTLS). The gateway certificate is generated from the host's interface addresses, so on AWS that means the private VPC IP — a client dialling the public address fails the TLS handshake. Tell the server its public name:

# /etc/k8e/config.yaml  (the k8e server/agent daemon config)
sandbox-advertise-hostname: 203.0.113.10     # a bare DNS name or a bare IP
sudo systemctl restart k8e.service

A bare name or a bare IP, nothing else — no scheme, no port, no path. Restart the service; the certificate regenerates itself.

Then create an API key (default TTL 30 days):

k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "e2b_key":"e2b_849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "ttl_days":30,"expires_at":"..."}

Keep both halves of that output: the bare hex key is what k8e-sandbox-cli --apikey wants, and the e2b_key (same hex with an e2b_ prefix) is what the official E2B SDKs want — their validateApiKey rejects a bare hex token before any request goes out.

3b — On the client: download, trust the CA, connect

# Download the sandbox CLI (~44MB) — pick your platform suffix
#   k8e-sandbox-cli-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

# Symlink the plain command name to the downloaded file (do not rename)
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli

The gateway uses a private CA, so the first connect needs that CA. Export it on the server:

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

Copy it to the client machine over any channel you trust (scp, a shared volume, your secret store — it is a public certificate, not a secret), then connect:

# on the client
./k8e-sandbox-cli --endpoint 203.0.113.10:50051 --apikey 849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9 \
  connect --ca-file ~/sandbox-ca.crt

connect authenticates over mTLS, remembers the gateway, puts the CLI on PATH, and installs the /k8e-sandbox skill into your agent harness.

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 and no CA needed.

3c — Prove it works

One command exercises the whole path — API key, client certificate, gateway, warm pool, runtime:

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

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

Optional multi-cluster profiles — ~/.k8e/sandbox/profiles.yaml, not the server's /etc/k8e/config.yaml: ./k8e-sandbox-cli --profile prod connect --apikey <key>

Platform binaries: k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64} (Windows: k8e-sandbox-cli-windows-amd64.exe, symlink via mklink k8e-sandbox-cli.exe k8e-sandbox-cli-windows-amd64.exe)

One binary, two names: the downloaded platform-suffixed file is the k8e-sandbox-cli command the skill uses — the symlink is just a plain-name alias. connect installs the /k8e-sandbox skill (and may symlink into ~/.local/bin/), so every skill example (k8e-sandbox-cli run ...) is the same file you just downloaded.

Config files are not the same: /etc/k8e/config.yaml is for the k8e server/agent daemon. CLI multi-cluster profiles live in ~/.k8e/sandbox/profiles.yaml. mTLS certs land in ~/.k8e/sandbox/{ca.crt,client.crt,client.key} (90-day certs, auto-renew when <30 days remain).

Then ask your agent naturally:

"Run this Python snippet in a sandbox"

The agent executes k8e-sandbox-cli run automatically — no session management needed.

Supported agents: Claude Code, Codex, Pi.

Step 4 — Port an Existing E2B App (optional)

If your code already speaks E2B, point it at the same cluster — no rewrite:

export E2B_API_KEY="e2b_849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9"   # the e2b_key from 4a
export E2B_API_URL="http://203.0.113.10:80"          # the cluster's Gateway, HTTP :80
export E2B_SANDBOX_URL="http://203.0.113.10:80/e2b/envd"

The official SDKs, unmodified, then talk to your cluster. See Sandbox with the Official E2B SDK for the full walkthrough — including the two things that bite first: the template argument is a runtime class (gvisor), and the Code Interpreter SDK is not supported.

Next: work through the hands-on Sandbox Examples — from a one-line marquee to a full Vue website, all driven from your agent through the skill.