Integration

Python SDK

boxkite-client talks to a hosted control-plane over HTTP. Distinct from the boxkite/boxkite-sandbox package, which embeds SandboxManagerdirectly against your own cluster — use this client when you're talking to someone else's already-running control-plane, hosted or self-hosted.

Install

terminal

pip install boxkite-client
pip install boxkite-client[langchain]  # for create_sandbox_tools

Construct a client

quickstart.py

from boxkite_client import BoxkiteClient

client = BoxkiteClient(base_url="https://your-control-plane.example.com", api_key="bxk_live_...")

with client.sandbox(label="demo") as sb:
    result = sb.exec("python3 -c 'print(1 + 1)'")
    print(result["stdout"])  # "2\n"
# sandbox is destroyed automatically here, even if an exception was raised above

client.sandbox(...) is a context manager that creates a sandbox and destroys it on exit. Without it, you own create/destroy yourself via client.create_sandbox(...)/client.destroy_sandbox(...) — see the Sandboxes page for every parameter both accept (size/storage/lifetime/count), and every other capability page for the corresponding sb.*/client.* method.

Async

Same shapes, AsyncBoxkiteClient + async with:

async_quickstart.py

import asyncio
from boxkite_client import AsyncBoxkiteClient

async def main():
    client = AsyncBoxkiteClient(base_url="https://your-control-plane.example.com", api_key="bxk_live_...")
    async with client.sandbox() as sb:
        result = await sb.exec("echo hi")
        print(result["stdout"])
    await client.aclose()

asyncio.run(main())

Every capability, from this client

Sandboxes — create_sandbox/get_sandbox/list_sandboxes/destroy_sandbox
Process & exec — sb.exec(...), start_process/get_process_output/send_process_input/stop_process/list_processes
File system — file_create/view/str_replace/ls/glob/grep
Command allowlist — get_allowed_commands/set_allowed_commands/clear_allowed_commands
Custom sandbox images — create_image/get_image/list_images/delete_image, opt-in declarative builder
Independent storage volumes — create_volume/get_volume/list_volumes/delete_volume, opt-in PVC-backed storage
Secrets management — create_sandbox(secret_names=[...]), http_request()
Webhooks — create_webhook/list_webhooks/delete_webhook/list_webhook_deliveries
Network ingress & previews — create_preview_url/revoke_preview_url
Audit log & takeover — get_log/watch/takeover

LangChain agent

agent.py

from boxkite_client import BoxkiteClient
from boxkite_client.langchain_tools import create_sandbox_tools

client = BoxkiteClient(base_url="https://your-control-plane.example.com", api_key="bxk_live_...")
sandbox = client.create_sandbox(label="agent-session")

tools = create_sandbox_tools(client, sandbox["id"])
# tools = [bash_tool, file_create, view, str_replace, ls, glob, grep,
#   start_process, get_process_output, send_process_input, stop_process,
#   list_processes] -- hand
# these to any LangChain/LangGraph agent, same names/shapes as boxkite.tools' own factory.

Error handling

Every non-2xx response raises BoxkiteApiError (with .status_code, .code, .message from the control-plane's error envelope). A network-level failure (DNS, TLS, timeout) raises BoxkiteConnectionError. Both subclass BoxkiteError.