Boxkite

boxkite

Website · Quickstart · Docs · Self-hosting · Security · Examples

▶ Watch the demo

The missing batteries-included, self-hostable sandbox for agent code execution.

Most "agent sandbox" projects give you raw isolation — a pod, a VM, a container — and leave you to build the tool surface an LLM agent actually needs on top of it. boxkite is the other half: a complete bash/python/file/search/process tool surface running inside real Kubernetes pod isolation, self-hostable end to end. Point your agent framework at it and you have a real sandbox in minutes, on infrastructure you control.

• 15 framework-agnostic tools (plus an opt-in 8-tool git set) — LangChain,

LangGraph, LlamaIndex, CrewAI, AutoGen, the OpenAI Agents SDK, or plain function calling, with no required dependency on any of them

• One Kubernetes pod per session — non-root, all capabilities dropped,

read-only root filesystem, network egress denied by default

• A hosted-API control-plane you run yourself — accounts, API keys,

fair-use limits, and client SDKs in four languages, if you want a real multi-tenant API in front of the sandbox instead of embedding it directly

• CLI, MCP server, Helm chart, and a one-click Render deploy for the

control-plane — see [Self-hosting](#self-hosting)

• Nothing held back. Every piece here — runtime, control-plane, all four

SDKs, the MCP server — is Apache-2.0-licensed and self-hostable; there's no separate closed hosted-only tier

Who this is for: teams building their own agent products that need isolated, multi-tenant code execution at scale. It's not a single-user local dev-session sandbox like the built-in bash tool in an IDE or CLI coding agent — if you just want your own assistant to run shell commands on your machine, boxkite is the wrong layer.

Start Here

If you are new to the repo, use this decision tree:

1. I just want to try the sandbox locally

Use boxkite up from the Quickstart below. This is the fastest path and does not require Kubernetes.

1. I want the real Kubernetes deployment on my laptop

Use [deploy/local-kind/README.md](deploy/local-kind/README.md). It explains the kind-based flow, the Apple Silicon limitation, and the kubectl proxy step.

1. I want the hosted API / multi-tenant control-plane

Use the control-plane section below, then the [examples/hosted_control_plane/](examples/hostedcontrolplane/) guide.

For contributors, the important mental model is: the root package gives you the sandbox runtime, while control-plane/, the SDKs, and mcp-server/ are separate packages with their own installs and tests.

Quickstart

Clone the repo, create a virtualenv, install the root package, then start the local stack:

git clone https://github.com/EvAlssment/boxkite.git boxkite && cd boxkite
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
boxkite up                # builds + starts sandbox, sidecar, and local MinIO
boxkite exec "python3 -c 'print(1 + 1)'"

> The PyPI name is boxkite-sandbox, not boxkite (already taken). Install > it with pip install -e ".[dev]" from the repo root; the import path > (import boxkite) and the boxkite CLI command are unaffected.

If boxkite up succeeds, the quickest smoke test is:

boxkite exec "python3 -c 'print(1 + 1)'"
boxkite files ls /

That confirms the sandbox, the sidecar, and the CLI are talking to each other correctly.

from uuid import uuid4
from boxkite import SandboxManager
from boxkite.tools import create_sandbox_tool_specs

manager = SandboxManager()
session_id = str(uuid4())
await manager.create_session(organization_id=uuid4(), session_id=session_id)

specs = create_sandbox_tool_specs(sandbox_manager=manager, session_id=session_id)
bash_tool = next(s for s in specs if s.name == "bash_tool")
result = await bash_tool.handler(command="echo hello from boxkite")

Framework adapters (boxkite.tools.adapters) convert the same tool specs for LangChain, LlamaIndex, the OpenAI Agents SDK, or plain OpenAI/Anthropic/ Gemini/Mistral function-calling schemas — see the full integration guide and [examples/](examples/) for a runnable version of every framework.

Self-hosting

Everything in this repo — including the control-plane/ hosted multi-tenant API — is something you deploy yourself:

• Real Kubernetes — two steps. First lay down the cluster prerequisites

(RBAC, NetworkPolicy, pod-security admission policy, ServiceAccount, Config/Secret scaffolding) by applying deploy/rbac.yaml/ network-policy.yaml/pod-security-policy.yaml, or helm install boxkite deploy/helm/boxkite. This chart does not deploy the control-plane itself (it has no Deployment/Service) — the per-session sandbox pods are created programmatically by the control-plane at runtime. Then deploy the control-plane/ API separately (see the Render button below or the developer docs). A local kind cluster works too: ./deploy/local-kind/setup.sh.

• One-click Render deploy for the control-plane API —

[](https://render.com/deploy?repo=https://github.com/EvAlssment/boxkite) (still needs a real Kubernetes cluster for actual sandbox execution).

• docker-compose, for local iteration without a cluster — see the

Quickstart above.

> docker-compose mode shares a PID namespace with the sandbox container and > execs into it via nsenter, the same mechanism the Kubernetes runtime > uses — it no longer needs (or mounts) the host's Docker socket. See > [SECURITY.md](SECURITY.md) for the current list of disclosed limitations.

Full walkthroughs for every path above (Kubernetes, Helm, Render, the boxkite CLI's hosted mode, secrets, webhooks, MCP, and every SDK) live on the developer docs site.

Run the control-plane locally

The control-plane/ multi-tenant API is a separate service from the boxkite up SDK path — it is not part of deploy/docker-compose.yml, and you run it on its own. To bring it up against a throwaway SQLite database (no Postgres required) for API exploration:

cd control-plane
uv venv                              # create .venv
uv pip install -e '../[dev]'         # install the boxkite runtime (sibling pkg)
uv pip install -e '.[dev]'           # install the control-plane itself
ENVIRONMENT=development DATABASE_URL=sqlite+aiosqlite:///./cp.db \
  uv run uvicorn control_plane.main:app --port 8099

Then check it's up:

• http://localhost:8099/health — liveness (process is up)
• http://localhost:8099/health/ready — readiness (round-trips a DB query)
• http://localhost:8099/docs — interactive OpenAPI docs

This gets you the API surface (accounts, API keys, session bookkeeping), but actually executing sandbox pods still needs a real Kubernetes cluster — the control-plane creates per-session pods programmatically at runtime (a local kind cluster via deploy/local-kind/setup.sh works). Against SQLite with no cluster you can exercise the HTTP/auth surface, not real code execution.

What's in this repo

One repo, several independently-versioned pieces, kept together deliberately (see [CONTRIBUTING.md](CONTRIBUTING.md)):

| Piece | What it is | |---|---| | src/boxkite/ (boxkite-sandbox on PyPI) | The core: SandboxManager, WarmPoolManager, and the 15+ tool boxkite.tools surface. Embed this directly against your own cluster. | | sidecar/ | The FastAPI service that runs in every sandbox pod — filesystem I/O, command exec via nsenter, storage sync. | | control-plane/ | Optional hosted-API layer in front of SandboxManager — accounts, API keys, fair-use limits. | | sdk-python/, sdk-js/, sdk-go/, sdk-rust/ | Thin HTTP clients for your own running control-plane. | | mcp-server/ (boxkite-mcp) | Wraps the Python SDK as an MCP tool source for Claude Code, Claude Desktop, Codex, or Cursor. | | handoff-cli/ (boxkite-handoff) | Moves an in-progress local Claude Code/Codex CLI/opencode session into a fresh sandbox, full conversation history included — see [docs/handoff-adapters.md](docs/handoff-adapters.md). Not yet published. | | bastion/ | Standalone SSH server bridging into a session's human-takeover WebSocket. | | deploy/ | Kubernetes manifests, Helm chart, Dockerfiles, docker-compose, Render Blueprint. | | examples/ | Runnable cookbook — LangGraph, LangChain, raw HTTP, OpenAI/Gemini/Mistral function calling, and more. |

Security

boxkite executes arbitrary, agent-generated code — its security posture is layered defense in depth: a per-pod shared-secret sidecar auth token, a fresh empty network namespace on every exec call, non-root execution with every Linux capability dropped, and a read-only root filesystem. No single one of these is meant to stand alone.

See [SECURITY.md](SECURITY.md) for the full model, known limitations, and how to report a vulnerability privately — this project runs arbitrary code, so a sandbox-escape report deserves a fast, private path, not a public issue. The security model guide covers the same ground with runnable examples.

Published packages and images

| Package | Registry | |---|---| | boxkite-sandbox | PyPI | | boxkite-client (Python) | PyPI | | boxkite-client (JS/TS) | npm | | boxkite-mcp | PyPI | | boxkite-client (Go) | pkg.go.dev | | boxkite-client (Rust) | crates.io |

Container images are published to GHCR (ghcr.io/evalssment/…):

| Image | Architectures | |---|---| | boxkite-sandbox | linux/amd64 only | | boxkite-sandbox-minimal | linux/amd64, linux/arm64 | | boxkite-sidecar | linux/amd64, linux/arm64 | | boxkite-control-plane | linux/amd64, linux/arm64 |

> boxkite-sandbox is amd64-only. Its Dockerfile deliberately hard-fails on > arm64 because the pinned Chrome-for-Testing release has no linux/arm64 build > (deploy/sandbox.Dockerfile). arm64 / Apple-Silicon users should use > boxkite-sandbox-minimal (multi-arch, no Chrome/LibreOffice/pandoc stack), > or build/run the full image under linux/amd64 emulation — docker-compose.yml > already forces platform: linux/amd64 for exactly this reason. The other three > images are multi-arch.

License

[Apache 2.0](LICENSE) — permissive, with an explicit patent grant. Use, modify, self-host, or build a competing hosted service on top of boxkite; there's no restriction.

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) — we use the Developer Certificate of Origin (git commit -s), not a CLA.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EvAlssment
• Source: EvAlssment/boxkite
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.