Integration

Python SDK

boxxkite-clienttalks to a control-plane over HTTP — either boxxkite's own hosted cloud at api.boxxkite.com (the examples below use it directly), or your own self-hosted deployment, just by swapping base_url. Distinct from the boxxkite/boxxkite-sandbox package, which embeds SandboxManager directly against your own cluster instead of talking to a control-plane at all.

Install

terminal

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

Construct a client

quickstart.py

from boxxkite_client import BoxxkiteClient

client = BoxxkiteClient(base_url="https://api.boxxkite.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, AsyncBoxxkiteClient + async with:

async_quickstart.py

import asyncio
from boxxkite_client import AsyncBoxxkiteClient

async def main():
    client = AsyncBoxxkiteClient(base_url="https://api.boxxkite.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 boxxkite_client import BoxxkiteClient
from boxxkite_client.langchain_tools import create_sandbox_tools

client = BoxxkiteClient(base_url="https://api.boxxkite.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 boxxkite.tools' own factory.

Error handling

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