boxxkite-client
A Python client for a hosted boxxkite control-plane — create sandboxes,
run commands, edit files, over HTTP. Not the boxxkite package itself
(boxxkite-sandbox, which embeds SandboxManager against your own
Kubernetes cluster) — use this to talk to someone else's running
control-plane, hosted or self-hosted, over its API.
Install
pip install boxxkite-client
pip install boxxkite-client[langchain] # for create_sandbox_tools
Quickstart
from boxxkite_client import BoxxkiteClient
client = BoxxkiteClient(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"
sb.file_create("notes.txt", "hello from boxxkite-client\n")
print(sb.view("notes.txt")["content"])
# sandbox is destroyed automatically here, even if an exception was raised above
Also available: AsyncBoxxkiteClient (same shapes, async/await),
file/directory search (ls/glob/grep), long-running background
processes (start_process/get_process_output/stop_process), signed
preview URLs for exposing a port, an audit-log feed (get_log/watch),
interactive human takeover over a raw WebSocket, desktop (GUI) takeover
over the same raw-WebSocket pattern, secret management
(create_secret/list_secrets/delete_secret, for use via
create_sandbox(secret_names=[...])), filesystem snapshot management
(create_snapshot/list_snapshots/get_snapshot/restore_snapshot/
delete_snapshot), and a create_sandbox_tools()
LangChain factory. Full reference with examples
for all of these: docs/API.md.
Error handling
Every non-2xx response raises BoxxkiteApiError (.status_code, .code,
.message). A network-level failure raises BoxxkiteConnectionError. Both
subclass BoxxkiteError.
from boxxkite_client import BoxxkiteApiError
try:
client.exec(sandbox["id"], "echo hi")
except BoxxkiteApiError as exc:
if exc.code == "concurrent_sandbox_limit_reached":
... # back off, destroy an old session, etc.
Retries
Automatic retry is off by default. Pass a RetryConfig to enable it;
RetryConfig() carries sensible defaults (2 retries, exponential backoff
with full jitter, Retry-After honored):
from boxxkite_client import BoxxkiteClient, RetryConfig
client = BoxxkiteClient(base_url="...", api_key="...", retry=RetryConfig())
Only idempotent verbs (GET/HEAD/PUT/DELETE/OPTIONS) are retried,
and only on a connection failure or a transient status (429, 500, 502, 503,
504) — a non-idempotent POST (create-sandbox/secret/webhook) is never
retried, so this can't double-create a resource. AsyncBoxxkiteClient takes
the same retry= argument and awaits its backoff. Every field of
RetryConfig is tunable if the defaults don't fit.
Development
pip install -e ".[dev,langchain]"
pytest tests/
Tests mock the control-plane with httpx.MockTransport — no real deployment needed.
Related tools
Moving an in-progress local Claude Code/Codex CLI/opencode/Cursor session
(full conversation history, not just a diff) into a fresh boxxkite sandbox
is handled by boxxkite handoff <tool>, part of the main boxxkite CLI
and built on this SDK — see
../docs/handoff-adapters.md.
See the root README for what boxxkite is and the full self-hosting story.
Questions, bug reports, or need a usage-limit bump? Join the Discord.
Metadata
Release files for boxxkite-client 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| boxxkite_client-0.8.0.tar.gz | 46.6 kB | Without provenance | Details for boxxkite_client-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| boxxkite_client-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for boxxkite_client-0.8.0-py3-none-any.whl |
Total release size: 75.2 kB
Release files / boxxkite_client-0.8.0.tar.gz
| Download URL | boxxkite_client-0.8.0.tar.gz |
|---|---|
| Size | 46.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2ad480318bcfa5d649e1fcd2036e21fa578d4cae34c12b77ee1560080121d08b
|
|
BLAKE2b-256 checksum How to use checksums |
ce932e695c5942c3fad632867d9051f0dba99a973b1a44a622973190a1032577
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / boxxkite_client-0.8.0-py3-none-any.whl
| Download URL | boxxkite_client-0.8.0-py3-none-any.whl |
|---|---|
| Size | 28.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a3475f27ae111b4248b66660c4cd9ee66d1913f87c044645f28821ff625eef97
|
|
BLAKE2b-256 checksum How to use checksums |
34937590d366de39102a706935665bc3c47c3da1e0bbae5fc9ed083f8b02a1f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for boxxkite-client 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.