drukbox-python-sdk

Async Python client for the Drukbox host API.

The SDK provisions sandbox VMs, reads host state, deletes hosts, and returns the SSH connection details a caller needs. It speaks HTTP only: SSH sessions, file transfer, command execution, and retry orchestration belong in the caller.

Install

pip install drukbox-python-sdk
uv add drukbox-python-sdk

Usage

from drukbox_sdk import SandboxAPI

sandbox = SandboxAPI(
    base_url="https://sandbox.internal.ts.net",
    token="...",
)

try:
    host = await sandbox.create_host(
        image="ghcr.io/drukbox/sandbox:abc123",
        env={"FOO": "bar"},
        idempotency_key="agent-run-42",
    )
    # Dial whichever reachable address fits your network: host.external_ssh_host
    # for the provider's public path (may be empty when the service runs an
    # AWS-with-Tailscale-on deployment) or host.internal_ssh_host for the
    # tailnet MagicDNS name (only when Tailscale is enabled). Use host.known_hosts
    # for SSH host-key verification. If the provider mints a per-VM keypair
    # (AWS with Tailscale off), host.private_key carries the private half —
    # returned exactly once at create time; subsequent get_host returns None.
finally:
    await sandbox.delete_host(host.id)
    await sandbox.aclose()

create_host blocks until the host is active — typically ~10–30s, up to a few minutes worst case. The SDK's default timeout (300s) covers this. Pass an idempotency_key for retry safety: a retry with the same key after a successful provision returns the original host instead of creating a duplicate.

SandboxAPI.from_env(prefix="SANDBOX_") reads SANDBOX_SERVICE_URL, SANDBOX_SERVICE_TOKEN, and optional SANDBOX_SERVICE_TIMEOUT.

Contract

Public exports live in drukbox_sdk:

SandboxAPI
SandboxHost
SandboxAPIError and typed subclasses for auth, not found, conflict, unavailable, and unclassified response errors

Supported host operations:

create_host
get_host
attach
list_hosts
delete_host
aclose

create_host supports the service's optional image, env, expires_at, and Idempotency-Key inputs.

The SDK does not mint Tailscale auth keys, manage ACLs, establish SSH, provision Linux users, transfer files, or run remote commands.

Development

uv sync
uv run ruff check
uv run ruff format --check
uv run pyright
uv run pytest

Tests use respx to fake the Drukbox HTTP API. They do not need a real network, VM provider, or Drukbox service.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

drukbox_python_sdk-0.0.3.tar.gz (12.4 kB view details)

Uploaded Jun 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

drukbox_python_sdk-0.0.3-py3-none-any.whl (8.2 kB view details)

Uploaded Jun 9, 2026 Python 3

File details

Details for the file drukbox_python_sdk-0.0.3.tar.gz.

File metadata

Download URL: drukbox_python_sdk-0.0.3.tar.gz
Upload date: Jun 9, 2026
Size: 12.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for drukbox_python_sdk-0.0.3.tar.gz
Algorithm	Hash digest
SHA256	`bceef10af88743766fe73fd9446c5c60b10a30892cb52b2c304b3c8c3270e346`
MD5	`c61f601b4cce9d3911fd7a6023f82473`
BLAKE2b-256	`ffbeeb251f169f7a0b7dc5e5f36e69264cf5356faf2cc828a5f58f96a845984c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for drukbox_python_sdk-0.0.3.tar.gz:

Publisher: release.yml on clawhaven/drukbox-python-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: drukbox_python_sdk-0.0.3.tar.gz
- Subject digest: bceef10af88743766fe73fd9446c5c60b10a30892cb52b2c304b3c8c3270e346
- Sigstore transparency entry: 1764680728
- Sigstore integration time: Jun 9, 2026
Source repository:
- Permalink: clawhaven/drukbox-python-sdk@309aad7d0f8aa4e728e8aa73cdcf9aef0d9440b6
- Branch / Tag: refs/heads/main
- Owner: https://github.com/clawhaven
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@309aad7d0f8aa4e728e8aa73cdcf9aef0d9440b6
- Trigger Event: workflow_dispatch