Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

Zipbox SDKs

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.

Authentication

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.

Surface

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.

Errors

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.

Layout

  • 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 /zipbox pane and commands (hooks/, tested by claude plugin test), and the zipbox-sdk skill. Install it with claude plugin marketplace add tribes-protocol/zipbox-sdks, then claude plugin install zipbox@zipbox-sdks; see zipbox.ai/docs/integrations.
  • .claude-plugin/marketplace.json — the marketplace that lists that plugin. The mirror export copies harnesses/setup/skills/zipbox-sdk/ (with its generated references/) to skills/zipbox-sdk/ for npx skills add, and into claude-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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages