Drive Zipbox boxes from code: create a box, run commands, move files, open a terminal, publish a port, pause it when you are done. Nothing on a box stops on a clock.
| Language | Package | Path | Docs |
|---|---|---|---|
| TypeScript | @zipbox/sdk (npm) |
typescript/ |
zipbox.ai/docs/sdk-ts |
| Python | zipbox (PyPI) |
python/ |
zipbox.ai/docs/sdk-python |
| Go | github.com/tribes-protocol/zipbox-go |
go/ |
zipbox.ai/docs/sdk-go |
| Rust | zipbox (crates.io) |
rust/ |
zipbox.ai/docs/sdk-rust |
| CLI | zipbox (Homebrew, curl, PowerShell) |
go/cmd/zipbox |
zipbox.ai/docs/cli |
Every SDK is a thin, hand-written client over one contract
(packages/public-api-contract/openapi.json, served at
zipbox.ai/openapi.json) and passes the same
conformance suite.
Create an API key at zipbox.ai → Settings → API keys and export it:
export ZIPBOX_API_KEY=zb_…The SDKs read ZIPBOX_API_KEY (and optionally ZIPBOX_API_URL) when no key is passed.
Box tokens — the per-box credential a box accepts — are fetched and cached by the
client; you never handle them. Nor do you handle a box's address: a created box answers
first on its machine's boot address and moves once, to box--<name>, a few minutes
later, and the client follows it.
The same operations with the same parameters, defaults and semantics in every language,
in that language's idiom (.cursor/rules/sdk-feature-and-param-parity.mdc). A change to
one SDK's surface lands in all four, the docs and the conformance fixtures together.
| Operation | TypeScript | Python | Go | Rust |
|---|---|---|---|---|
| Client | new Zipbox({ apiKey, baseUrl, maxRetries, … }) |
Zipbox(api_key=, base_url=, max_retries=, …) / AsyncZipbox |
zipbox.New(apiKey, opts...) |
Zipbox::builder()…build() |
| Create (waits until ready) | zb.sandboxes.create({ name }) |
zb.sandboxes.create(name=) |
c.Sandboxes.Create(ctx, opts) |
zb.sandboxes().create(opts) |
| Get or create by name | zb.sandboxes.getOrCreate(name, { tier }) |
zb.sandboxes.get_or_create(name, tier=) |
c.Sandboxes.GetOrCreate(ctx, name, zipbox.CreateOptions{Tier}) |
zb.sandboxes().get_or_create_with(name, opts) |
| Wait until ready | zb.sandboxes.waitReady(id) |
zb.sandboxes.wait_ready(id) |
c.Sandboxes.WaitReady(ctx, id) |
zb.sandboxes().wait_ready(id) |
| List / get | list() / get(id) |
list() / get(id) |
List(ctx) / Get(ctx, id) |
list() / get(id) |
| Pause / resume / restart | pause(id) / resume(id) (aliases stop / start) … |
pause(id) / resume(id) (aliases stop / start) … |
Pause(ctx, id) / Resume(ctx, id) (aliases Stop / Start) … |
pause(id) / resume(id) (aliases stop / start) … |
| Cancel a change in flight | cancelTransition(id) |
cancel_transition(id) |
CancelTransition(ctx, id) |
cancel_transition(id) |
| Fork a box (new identity) | fork(id, { name, sourcePolicy, private, tailscaleAuthKey, wait }) / getFork(id) |
fork(id, name=, source_policy=, private=, tailscale_auth_key=, wait=) / get_fork(id) |
Fork(ctx, id, zipbox.ForkOptions{Name, SourcePolicy, Private, TailscaleAuthKey, NoWait}) / GetFork(ctx, id) |
fork(id, ForkOptions { private: Some(true), ..ForkOptions::new(name, source_policy) }) / get_fork(id) |
| Delete (optionally no archive) | delete(id, { archive }) |
delete(id, archive=) |
Delete(ctx, id, zipbox.DeleteOptions{Archive}) |
delete_with(id, DeleteOptions { archive }) |
| Change tier | setTier(id, tier) |
set_tier(id, tier) |
SetTier(ctx, id, tier) |
set_tier(id, tier) |
| Run a command | box.exec(cmd) |
box.exec(cmd) |
box.Exec(ctx, cmd) |
box.exec(cmd) |
| Stream a command | box.execStream(cmd) (AsyncIterable) |
box.exec_stream(cmd) (iterator) |
box.ExecStream(ctx, cmd) |
box.exec_stream(cmd) (Stream) |
| Background command | box.execBackground(cmd) |
box.exec_background(cmd) |
box.ExecBackground(ctx, cmd) |
box.exec_background(cmd) |
| Run code | box.runCode(lang, code, { cwd }) |
box.run_code(lang, code, cwd=) |
box.RunCode(ctx, lang, code, opts...) |
box.run_code_with(lang, code, opts) |
| Command handle | box.commands.handle/get/events/stdin/closeStdin/signal |
box.commands.handle/get/events/stdin/close_stdin/signal |
box.Command(id), box.Commands.Get/Events/Stdin/CloseStdin/Signal |
box.commands().command/get/events/stdin/close_stdin/signal |
| Files | box.files.read/write/list/stat/mkdir/move/copy/delete/upload/download |
same, snake_case | box.Files.Read/Write/…/Copy/… |
box.files().read/write/…/copy/… |
| PTY | box.pty.create({ cols, rows }) / attach(id) → write, resize, takeover, close |
same | box.Pty.Create(ctx, opts) … |
box.pty().create(opts) … |
| Preview a port | box.preview.create(port) / remove(label) |
same | box.Preview.Create(ctx, port, label) |
box.preview().create(port, label) |
| Logs | box.logs({ since, lines, unit }) |
box.logs(since=, lines=, unit=) |
box.Logs(ctx, zipbox.LogOptions{Since, Lines, Unit}) |
box.logs(LogOptions { since, lines, unit }) |
| SSH line | box.sshInfo() |
box.ssh_info() |
box.SSHInfo(ctx) |
box.ssh_info() |
| Account | zb.account.balance() / usage() |
same | c.Account.Balance(ctx) … |
zb.account().balance() … |
| Tailscale | box.tailscale.status() / connect(authKey) / disconnect() |
box.tailscale.status() / connect(auth_key) / disconnect() |
box.Tailscale.Status(ctx) / Connect(ctx, authKey) / Disconnect(ctx) |
box.tailscale().status() / connect(auth_key) / disconnect() |
| Private mode | box.setPrivate(enabled) |
box.set_private(enabled) |
box.SetPrivate(ctx, enabled) |
box.set_private(enabled) |
box is the handle returned by create, get, getOrCreate or zb.sandbox(id). create
also takes private (a box that is never public); it then returns once the box is running,
because a private box is not ready until it joins a tailnet. getOrCreate takes every
create option except the name and applies them only when it creates the box: a box that
already has the name is returned as it is (a different tier is not an error and is not
resized). An account holds 250 machine names and a deleted box keeps its name, so reuse a
fixed pool of names with get-or-create rather than a fresh name per job; a new name past the
limit raises machine_limit_reached (zipbox.ai/docs/machine-limit).
pause returns the box once it reads paused and resume once it is ready: at once when the
server answers with that final state (200), else after a wait. Every wait (create,
getOrCreate, waitReady, resume, fork, and pause for paused) is
GET /sandbox/:id/wait?until=ready|paused, which the server answers when the box gets there; a
held answer that is still settling is asked again at once, with no deadline (a retryable
failed read waits on the poll backoff; an API older than /wait is polled on
GET /sandbox/:id). A wait for ready returns on ready or, for a private box, awaits_tailnet, and raises on
the rest, never retryable: paused box_not_running, a failed start start_failed, deleting
or gone conflict. Rows carry phase and allowedActions; a detail also carries readiness.
One retry rule: an error is retried when its retryable is true. The one exception is a box
call that never reached the box (a refused connection, DNS, a failed TLS handshake): every SDK
waits one rung of its backoff (500 ms doubling to 30 s, with jitter), re-reads the box with the
same wait, and retries on the address that read returns, with no attempt limit; the wait's
verdict on a paused, failed or deleted box ends it. See zipbox.ai/docs/http-api#status-phase-and-readiness.
tailscale.connect seals the auth key on the caller's machine to the box's own
agentPublicKey (P-256 ECDH → HKDF-SHA256 → AES-256-GCM, the same envelope the dashboard
seals) and sends only the ciphertext, so Zipbox never holds the key. Every SDK reproduces the
fixed-key vector in conformance/vectors/box_envelope.json byte for byte.
Every failure is one error type carrying code (invalid_request, unauthorized,
forbidden, not_found, insufficient_credits, conflict, rate_limited,
box_not_running, unavailable, machine_limit_reached, box_key_changed, tailnet_not_connected,
tailscale_unavailable_egress_lockdown, tailscale_requires_update, box_private_unreachable,
name_taken, source_unsupported, source_busy, pause_required, requires_interactive,
idempotency_mismatch, and a failed fork's source_gone, identity_reused, copy_failed,
start_failed), status, message, requestId, retryable,
retryAfterMs and docsUrl (https://zipbox.ai/docs/errors#<code>). A command that
exits non-zero is a result, never an error.
conformance/— fixtures every SDK runs against a mock server.examples/— runnable projects (framework integrations, CI, agents driving boxes).claude-plugin/— the Zipbox plugin for Claude Code: the hosted MCP server (.mcp.json), a mod with the/zipboxpane and commands (hooks/, tested byclaude plugin test), and thezipbox-sdkskill. Install it withclaude plugin marketplace add tribes-protocol/zipbox-sdks, thenclaude plugin install zipbox@zipbox-sdks; see zipbox.ai/docs/integrations..claude-plugin/marketplace.json— the marketplace that lists that plugin. The mirror export copiesharnesses/setup/skills/zipbox-sdk/(with its generatedreferences/) toskills/zipbox-sdk/fornpx skills add, and intoclaude-plugin/skills/zipbox-sdk/for the plugin.
This tree is the only place the SDKs are edited. Releases export it to the public
mirror tribes-protocol/zipbox-sdks (Apache-2.0), which the package registries and Go
module resolution point at.