Boxxkite

What is Boxxkite about?

Boxxkite delivers a complete, batteries‑included environment for executing LLM‑generated agent code safely. Each request spawns a dedicated Kubernetes pod with a non‑root user, dropped capabilities, a read‑only root filesystem, and network egress disabled by default. A sidecar service inside the pod exposes file, process, and tooling APIs, while an optional control‑plane offers account management, API keys, and usage limits.

How to use Boxxkite?

1. Local quickstart – clone the repo, create a virtual environment, and run boxxkite up. This starts the sandbox, sidecar, and a MinIO instance for storage.

   git clone https://github.com/EvAlssment/boxxkite.git && cd boxxkite
   python3 -m venv .venv && source .venv/bin/activate
   pip install -e "[dev]"
   boxxkite up
   boxxkite exec "python3 -c 'print(1 + 1)'"
   

2. Kubernetes deployment – apply the RBAC, network‑policy, and pod‑security manifests, then install the Helm chart (helm install boxxkite deploy/helm/boxxkite). Deploy the control-plane/ service separately (Render button or manual deployment). The control‑plane creates per‑session sandbox pods on‑the‑fly.
3. SDK integration – import the language‑specific client (boxxkite-client on PyPI, npm, Go, or crates.io) and call the HTTP endpoints, or embed SandboxManager directly in Python code.
4. MCP server – install the boxxkite-mcp Python package and run it as an MCP tool source to expose the sandbox to Claude Code, Claude Desktop, Codex, or Cursor.

Key features of Boxxkite

• 15+ built‑in tools (bash, python, file search, process control) plus an optional 8‑tool git suite.
• One Kubernetes pod per session, non‑root, all Linux capabilities dropped, read‑only root FS, network egress denied.
• Optional hosted‑API control‑plane with multi‑tenant accounts, API keys, and fair‑use limits.
• CLI, Helm chart, Docker‑Compose, and one‑click Render deployment options.
• SDKs in Python, JavaScript/TypeScript, Go, and Rust.
• MCP server (boxxkite-mcp) to integrate with Claude‑style coding assistants.
• Open‑source Apache‑2.0 license for every component.

Use cases of Boxxkite

• Enterprise agent platforms needing secure, isolated execution of user‑generated code at scale.
• Multi‑tenant SaaS products that expose LLM agents to customers while protecting the underlying infrastructure.
• Research prototyping where rapid iteration of new tool adapters (LangChain, LangGraph, LlamaIndex, etc.) is required.
• CI/CD pipelines that need a controlled environment for running untrusted scripts generated by AI.
• Educational sandboxes for teaching AI‑driven automation without giving direct host access.

FAQ

Q: Do I need a Kubernetes cluster to run Boxxkite? A: For the full sandbox you do. A local kind cluster or any Kubernetes‑compatible environment works. For quick local testing you can use Docker‑Compose, which emulates the pod isolation via nsenter.

Q: Can I run Boxxkite on Apple Silicon? A: The primary boxxkite-sandbox image is amd64‑only due to Chrome‑for‑Testing. Use the boxxkite-sandbox-minimal multi‑arch image or run the amd64 image under emulation.

Q: How does security work? A: Security is layered: per‑pod shared secret between sidecar and manager, fresh network namespace per exec, non‑root user, all capabilities dropped, read‑only root FS, and default network egress block. See SECURITY.md for details.

Q: What languages are supported for the SDK? A: Python, JavaScript/TypeScript, Go, and Rust, each published as a separate package.

Q: Is there a hosted SaaS version? A: The repository provides only self‑hostable components. You can deploy the control‑plane to a cloud provider (Render button) but you still manage the Kubernetes cluster that runs the sandbox pods.

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. boxxkite 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
• 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, boxxkite 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 boxxkite up from the Quickstart below. This is the fastest path and does not require Kubernetes.
2. I want the real Kubernetes deployment on my laptop
   Use deploy/local-kind/README.md. It explains the kind-based flow, the Apple Silicon limitation, and the kubectl proxy step.
3. I want the hosted API / multi-tenant control-plane
   Use the control-plane section below, then the examples/hosted_control_plane/ 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/boxxkite.git boxxkite && cd boxxkite
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
boxxkite up                # builds + starts sandbox, sidecar, and local MinIO
boxxkite exec "python3 -c 'print(1 + 1)'"

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

If boxxkite up succeeds, the quickest smoke test is:

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

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

from uuid import uuid4
from boxxkite import SandboxManager
from boxxkite.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 boxxkite")

Framework adapters (boxxkite.tools.adapters) convert the same tool specs for LangChain, LlamaIndex, the OpenAI Agents SDK, Google ADK, or plain OpenAI/ Anthropic/Gemini/Mistral function-calling schemas — see the full integration guide and 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 boxxkite deploy/helm/boxxkite. 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 — (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 for the current list of disclosed limitations.

Full walkthroughs for every path above (Kubernetes, Helm, Render, the boxxkite 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 boxxkite 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 boxxkite 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):

Piece	What it is
src/boxxkite/ (boxxkite-sandbox on PyPI)	The core: SandboxManager, WarmPoolManager, and the 15+ tool boxxkite.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/ (boxxkite-mcp)	Wraps the Python SDK as an MCP tool source for Claude Code, Claude Desktop, Codex, or Cursor.
src/boxxkite/handoff/ (boxxkite handoff <tool>, part of the main CLI)	Moves an in-progress local Claude Code/Codex CLI/opencode/Cursor session into a fresh sandbox, full conversation history included — see docs/handoff-adapters.md.
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

boxxkite 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 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
boxxkite-sandbox	PyPI
boxxkite-client (Python)	PyPI
boxxkite-client (JS/TS)	npm
boxxkite-mcp	PyPI
boxxkite-client (Go)	pkg.go.dev
boxxkite-client (Rust)	crates.io

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

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

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

Community

Join the Discord — get help from other users and maintainers, report a bug, ask for a usage-limit/credit bump, or discuss elevated access if you're a startup (dedicated thread for that once you're in).

License

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

Contributing

See CONTRIBUTING.md — we use the Developer Certificate of Origin (git commit -s), not a CLA. Questions before opening a PR? Ask in the Discord first.