Quickstart

1. Clone and configure

SIDECAR_AUTH_TOKEN is required, not optional — every sidecar route but /health checks it, and boxkite up (below) generates it for you, so a manual step is only needed if you run docker compose directly.

git clone https://github.com/EvAlssment/boxkite.git && cd boxkite
pip install boxkite-sandbox

2. Start the stack

boxkite up generates a fresh SIDECAR_AUTH_TOKEN, writes it to ~/.boxkite/local.env (so boxkite exec/files pick it up automatically), and runs docker compose up -d --build for you — the sandbox container, the sidecar HTTP API, and a local MinIO for S3-compatible storage.

boxkite up
# Generated a new SIDECAR_AUTH_TOKEN and wrote it to ~/.boxkite/local.env
# Starting docker compose stack from deploy/docker-compose.yml ...
# boxkite is up.
#   Health check:   curl http://localhost:8080/health

Auto-discovers deploy/docker-compose.yml by walking up from your current directory (and refuses to auto-start an unrelated compose file it happens to find — pass --compose-file <path> if that check ever gets in your way). Prefer to run docker compose yourself instead? See deploy/docker-compose.yml's own header comment for the manual equivalent.

3. Run a command

Local docker-compose mode has no session concept — one stack, one sidecar. boxkite exec talks to it directly.

boxkite exec "python3 -c 'print(1 + 1)'"
# 2
# exit code: 0

boxkite files create notes.txt --content "hello from boxkite"
boxkite files view notes.txt

Try it now

No local setup yet? Run a command in a real, throwaway sandbox right here before you clone anything.

4. Point a LangChain agent at it

Embed the same tool surface directly in Python, against your own running compose stack or a real cluster:

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

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

tools = create_sandbox_tools(sandbox_manager=manager, session_id=session_id)
# 15 tools by default: bash_tool, python_interpreter, file_create, view,
# str_replace, present_files, ls, glob, grep, start_process,
# get_process_output, send_process_input, stop_process, list_processes,
# watch_directory

Next: a real cluster, or a hosted control-plane

Compose mode is for kicking the tires — it has known, disclosed limits (a root sidecar with the host's Docker socket mounted, no per-exec network isolation). For the real pod-per-session isolation model, see:

• Kubernetes deployment — run boxkite against a real cluster.
• Hosted control-plane & CLI— sign up against someone else's (or your own) already-running control-plane instead of embedding SandboxManager yourself.
• Want to try running your own control-plane API without provisioning a cluster by hand first? deploy/render.yaml is a one-click Blueprint deploy for the control-plane API + managed Postgres on Render — you still point it at a real Kubernetes cluster (viaKUBECONFIG) for actual sandbox execution.