Guide

Quickstart

The fastest path to a running sandbox with nothing to sign up for: just docker compose and the boxxkiteCLI, running entirely on your own machine. A real cluster (or a local kind one) is only needed once you want the full pod-per-session isolation model. Would rather skip local setup entirely and use boxxkite's own hosted cloud instead? Jump straight to Hosted API & CLI — one boxxkite signup and you have a real sandbox, no docker compose or cluster required.

1. Clone and configure

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

terminal

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

2. Start the stack

boxxkite up generates a fresh SIDECAR_AUTH_TOKEN, writes it to ~/.boxxkite/local.env (so boxxkite 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.

terminal

boxxkite up
# Generated a new SIDECAR_AUTH_TOKEN and wrote it to ~/.boxxkite/local.env
# Starting docker compose stack from deploy/docker-compose.yml ...
# boxxkite 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. boxxkite exec talks to it directly.

terminal

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

boxxkite files create notes.txt --content "hello from boxxkite"
boxxkite 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.

demo-sandbox

Spin up a real, throwaway sandbox and run a command in it — right from this page.

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:

agent_setup.py

from uuid import uuid4
from boxxkite import SandboxManager
from boxxkite.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 boxxkite against a real cluster.
Hosted control-plane & CLI— sign up against boxxkite's own hosted cloud (api.boxxkite.com) 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.