Skip to main content

boxkite-client

PyPI

A Python client for a hosted boxkite control-plane — create sandboxes, run commands, edit files, over HTTP. Not the boxkite package itself (boxkite-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 boxkite-client
pip install boxkite-client[langchain]  # for create_sandbox_tools

Quickstart

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"

    sb.file_create("notes.txt", "hello from boxkite-client\n")
    print(sb.view("notes.txt")["content"])
# sandbox is destroyed automatically here, even if an exception was raised above

Also available: AsyncBoxkiteClient (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=[...])), 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 BoxkiteApiError (.status_code, .code, .message). A network-level failure raises BoxkiteConnectionError. Both subclass BoxkiteError.

from boxkite_client import BoxkiteApiError

try:
    client.exec(sandbox["id"], "echo hi")
except BoxkiteApiError 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 boxkite_client import BoxkiteClient, RetryConfig

client = BoxkiteClient(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. AsyncBoxkiteClient 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.

Moving an in-progress local Claude Code/Codex CLI/opencode session (full conversation history, not just a diff) into a fresh boxkite sandbox is handled by the separate boxkite-handoff CLI, built on this SDK — see ../docs/handoff-adapters.md and ../handoff-cli/README.md. Not yet published to PyPI.

See the root README for what boxkite is and the full self-hosting story.

Metadata

Release files for boxkite-client 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boxkite-client 0.2.2
File Size Uploaded Provenance Actions
boxkite_client-0.2.2.tar.gz 41.8 kB Without provenance Details for boxkite_client-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boxkite-client 0.2.2
File Interpreter ABI Platform Actions
boxkite_client-0.2.2-py3-none-any.whl Python 3 none any Details for boxkite_client-0.2.2-py3-none-any.whl

Total release size: 67.5 kB

Release files / boxkite_client-0.2.2.tar.gz

Download URL boxkite_client-0.2.2.tar.gz
Size 41.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3009a4266f04e92aef884de12223c78788fa4a9ce05bc46777586edddcecd820
BLAKE2b-256 checksum
How to use checksums
e8f1486b71e4c8ef6d3cbbfa4fc1490b283f80ccbb18f9838982efcb7dddb232
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / boxkite_client-0.2.2-py3-none-any.whl

Download URL boxkite_client-0.2.2-py3-none-any.whl
Size 25.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3bf3b3452d5dd1889c0bdd6b37f1e44aa20400aa3d58ff3e7c4e3c51760277dd
BLAKE2b-256 checksum
How to use checksums
a8d7d702ecc06d69b6c5f4c301a572dc3640e9e06f334c4388fab7ba48052e67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for boxkite-client 0.2.2

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page