Python SDK

The boxd package gives you programmatic access to the full boxd API — create and manage machines, run commands in them, stream output, move files, and manage proxies, snapshots, disks, env vars and secrets. It talks to the same API as the CLI, so everything you can do from the terminal you can do from Python. Requires Python 3.10+.

Install

pip install boxd

uv add boxd

Quick start

from boxd import Boxd

boxd = Boxd(api_key="bxd_...")

machine = boxd.machines.create("my-machine")
boxd.machines.wait_until_ready(machine.id)

result = boxd.machines.exec(machine.id, "uname -a")
print(result.stdout)

boxd.machines.delete(machine.id)
boxd.close()

The client is the only stateful object. Everything else is a namespace of flat methods that return plain data — a Machine is a record of fields, not a handle, and every operation takes the machine id (or name) as its first argument: boxd.<resource>.<verb>(id, ...). There are eight namespaces:

Namespace	For
`boxd.machines`	machines, plus `.files`, `.ports`, `.proxies`, `.checkpoints`
`boxd.snapshots`	reusable point-in-time captures
`boxd.disks`	persistent disks
`boxd.env`	environment variables
`boxd.secrets`	secrets (write-only values)
`boxd.orgs`	the organizations you belong to
`boxd.api_keys`	API keys
`boxd.account`	your identity and cluster defaults

The client

Boxd()                                            # production
Boxd(api_key="bxd_...")
Boxd(base_url="https://boxd.example.com:9443")    # any other cluster

base_url selects the cluster.

Argument	Environment variable	Default
`api_key`	`BOXD_API_KEY`	—
`token`	`BOXD_TOKEN`	—
`base_url`	`BOXD_BASE_URL` (or the deprecated `BOXD_API_URL`)	`http://boxd.sh:9443`
`timeout`	—	60 seconds
`max_retries`	—	2

All arguments are keyword-only. base_url accepts an optional scheme that controls TLS:

Value	Transport
`http://host:port`	plaintext
`https://host:port`	TLS
bare `host:port`	TLS, except `localhost` / `127.*`

Failed connections are retried up to max_retries times with exponential backoff. Timeouts are never retried — the request may already have been applied — and authentication failures are never retried either. The client holds a connection, so keep one around rather than making a new one per call. Close it when you’re done, or use it as a context manager:

with Boxd(api_key="bxd_...") as boxd:
    ...

Sync and async

Boxd and AsyncBoxd are two top-level classes with the same surface — same namespaces, same method names, same arguments, same return types. Switching is await and an import, not a rewrite.

from boxd import AsyncBoxd

async with AsyncBoxd(api_key="bxd_...") as boxd:
    machine = await boxd.machines.create("my-machine")
    result = await boxd.machines.exec(machine.id, "echo hello")

Use AsyncBoxd when you already have an event loop (FastAPI, asyncio scripts, anyio). Use Boxd everywhere else — scripts, notebooks, Django views.

	`Boxd`	`AsyncBoxd`
Call style	`boxd.machines.create(...)`	`await boxd.machines.create(...)`
Context manager	`with`	`async with`
Best for	scripts, CLIs, notebooks	FastAPI, async workers, concurrent fan-out

Authentication

Boxd(api_key="bxd_...")   # recommended
Boxd(token="...")         # a token you already hold
Boxd()                    # BOXD_API_KEY, then BOXD_TOKEN

Credentials are resolved in this order, first match wins:

an explicit token
an explicit api_key
BOXD_TOKEN
BOXD_API_KEY
automatic, inside a boxd machine (below)

If none of those produce a credential, the first request raises AuthenticationError. Mint a key with boxd auth keys create NAME (see the CLI), in the console, or with boxd.api_keys.create(). An API key is exchanged for a short-lived session and kept fresh for you. Revoking a key takes effect immediately, so if a key is revoked mid-run the next call raises AuthenticationError rather than retrying.

Inside a machine

Inside a boxd machine, Boxd() authenticates automatically — no API key, no configuration:

boxd = Boxd()
for machine in boxd.machines.list():
    print(machine.name, machine.status)

It also targets the cluster the surrounding machine belongs to, so the same code runs unchanged wherever it is deployed. An explicit base_url or credential still wins.

Inside a shared machine the SDK can manage the organization’s shared machines, but it cannot read env vars or secrets, and cannot reach machines that are private to another member. Pass an API key for those.

Machines

machine = boxd.machines.create("my-machine")
one     = boxd.machines.get("my-machine")   # id or name
all     = boxd.machines.list()              # list[Machine]
boxd.machines.delete("my-machine")

list() returns a plain list. Pass org="acme" for one organization’s machines, or all_contexts=True for everything you can reach. State:

boxd.machines.start(id)
boxd.machines.stop(id)
boxd.machines.reboot(id)
boxd.machines.pause(id)        # suspend to RAM — PauseResult(suspend_us=...)
boxd.machines.resume(id)       # ResumeResult(resume_us=...)
boxd.machines.hibernate(id)    # suspend to disk
boxd.machines.wake(id)

See Suspend & resume for the difference between stop/start (cold) and pause/resume (warm). Everything else:

fork = boxd.machines.fork("my-machine", "my-copy")   # live clone
boxd.machines.share(id)                              # visible to your whole org
boxd.machines.unshare(id)
boxd.machines.rename(id, "new-name")                 # returns the new name
boxd.machines.set_auto_suspend_timeout(id, 300)      # seconds; 0 disables
boxd.machines.set_auto_hibernate_timeout(id, 3600)
boxd.machines.wait_until_ready(id)                   # running *and* exec works
boxd.machines.suggest_name()                         # a free, generated name

rename reboots the machine. It is its own call rather than part of an update() for exactly that reason.

create and fork return once the machine is scheduled, not once it is usable. Call wait_until_ready before doing anything that depends on it running — especially before forking it again. It polls for up to 90 seconds by default (timeout=, poll_interval=, both in seconds).

Creating

boxd.machines.create(
    "builder",
    image="ubuntu:24.04",
    env={"API_URL": "https://example.com"},
    cmd=["/usr/local/bin/start"],
    restart_policy="always",          # "always" | "never"
    vcpu=2,
    memory="8G",
    disk="100G",
    auto_suspend_timeout=300,         # seconds; 0 disables
    auto_destroy_timeout=0,
    ssh=True,
)

# In an organization. `shared` makes it visible to every member.
boxd.machines.create(org="acme", shared=True)

# From a snapshot instead of an image.
boxd.machines.create("from-golden", from_snapshot="golden")

Sizing and lifecycle are flat keyword arguments — there is no config object. Every one is optional; create() boots the default image at the default size. fork(source, name) takes the same keywords, and anything you leave out is inherited from the source. Proxies and disk mounts are set up at create time with two small models:

from boxd import ProxyEntry, VolumeMount

boxd.machines.create(
    "api-server",
    proxies=[ProxyEntry(name="api", port=3000)],
    volumes=[VolumeMount(disk_id="d_...", mount_path="/data")],
)

A snapshot restores the machine that was captured, so create(from_snapshot=...) takes only name, org and the sizing keywords. Passing image, env, cmd, restart_policy or shared alongside it raises ValueError rather than silently ignoring them.

Renaming reboots the machine, so it is its own call. Everything else is readable straight off Machine.

The `Machine` record

machine.id
machine.name
machine.status            # "pending" | "starting" | "running" | "suspended" |
                          # "hibernated" | "stopped" | "failed" | "destroyed" | "migrating"
machine.image_ref         # the image the machine boots
machine.restart_policy    # str | None
machine.created_at        # datetime | None

machine.resources.vcpu           # the machine's CPU, memory and disk
machine.resources.memory_bytes
machine.resources.disk_bytes

machine.org               # OrgRef(id, name) | None — None = your personal quota
machine.shared            # shared with that org, or private to you

machine.access.ssh_port   # the port to SSH to; None if it has none yet
machine.access.domain     # the domain the machine is addressed under
machine.access.url        # the machine's public HTTPS address

machine.idle.suspend_after     # seconds of inactivity before each action;
machine.idle.hibernate_after   # 0 disables it
machine.idle.destroy_after

machine.source            # MachineSource | None — None = booted from an image
machine.source.kind       # "fork" | "snapshot"
machine.source.name       # the source machine, or the snapshot name
machine.source.version    # the snapshot version; a fork has none
machine.source.id         # the machine or snapshot this came from

machine.hibernated_at     # when it went to disk; None = not hibernated
machine.last_connected_at # datetime | None — None = never connected
machine.boot_time_ms      # how long the last boot took

org is the organization the machine belongs to and is billed to; shared says whether your teammates can see it. A private machine can still be org-billed, so org set with shared=False is normal, not a contradiction — see Organizations. source.id may not resolve if the machine or snapshot it points at was since deleted. A lookup that finds nothing is normal. Models are pydantic, so machine.model_dump() gives you a plain dict. An unrecognised status is passed through rather than rejected, so a machine in a newly added state still prints.

Exec

One-shot exec collects the output:

result = boxd.machines.exec(id, "cargo build")
result.stdout      # str
result.stderr      # str
result.exit_code   # int
result.success     # bool — exit_code == 0

boxd.machines.exec(id, ["echo", "a b"])              # a list is quoted for you
boxd.machines.exec(id, "env", env={"FOO": "bar"})
boxd.machines.exec(id, "pytest", timeout=30)         # seconds

A list command is shell-quoted for you; a string is passed through as written. timeout is in seconds and gives up on the call — the remote process may keep running. exec also takes tty, cols and rows: under a PTY the terminal merges stderr into stdout, so stderr comes back empty and everything lands in stdout. For anything interactive, stream_exec gives you a live session — the one handle in the SDK, because a bidirectional stream really is stateful:

with boxd.machines.stream_exec(id, command="bash", tty=True) as stream:
    stream.write(b"ls\n")
    stream.write_eof()
    for chunk in stream:
        print(chunk.decode(errors="replace"), end="")
    print("exited", stream.exit_code)

Iterating the stream yields merged output — what a terminal would show. iter_chunks() yields OutputChunk(data, is_stderr) when you need the two streams apart. Under tty=True the terminal merges them, so everything arrives as stdout; set tty=False if you need the split. exit_code is None until the stream is exhausted. Set the terminal size with cols/rows, and call stream.resize(cols, rows) when the local terminal changes size:

import shutil, signal

cols, rows = shutil.get_terminal_size()
stream = boxd.machines.stream_exec(id, command="htop", tty=True, cols=cols, rows=rows)
signal.signal(signal.SIGWINCH, lambda *_: stream.resize(*shutil.get_terminal_size()))

Unset cols/rows fall back to 80×24. resize() on a non-PTY exec is a harmless no-op. Headless one-shots that read stdin (jq, cat, claude -p) hang waiting for input. Pass close_stdin=True to send end-of-input immediately — or call write_eof() yourself. Combining it with tty=True raises ValueError, since a shell needs stdin open.

Logs

for chunk in boxd.machines.logs(id):
    print(chunk.decode(errors="replace"), end="")

for chunk in boxd.machines.logs(id, follow=True):   # stays open
    ...

follow=True keeps the stream open for new output.

Files

boxd.machines.files.upload(id, "/app/config.json", '{"debug": true}')
boxd.machines.files.upload(id, "/app/data.bin", open("local.bin", "rb").read())
data = boxd.machines.files.download(id, "/app/output.json")   # bytes

upload takes str or bytes and returns the number of bytes written; large uploads are chunked for you. Paths inside the machine are absolute, or relative to /home/boxd.

Ports

Raw TCP/UDP forwards on a public address — see Port forwarding. Max 3 per machine.

fwd = boxd.machines.ports.expose(id, 5432, protocol="tcp")
fwd.dns             # hostname to connect to
fwd.public_port     # port to connect on
fwd.machine_port    # the port inside the machine
fwd.protocol        # "tcp" | "udp" | "both"

boxd.machines.ports.list(id)    # one machine's forwards
boxd.machines.ports.list()      # every forward you own
boxd.machines.ports.unexpose(id, 5432)

Re-exposing the same machine port keeps its public port and just updates the protocol; "both" shares one public port across TCP and UDP.

On AsyncBoxd, ports.list() takes no machine argument — it returns every forward you own. Filter on .machine_id or .machine_name.

Proxies

HTTPS routes into a machine — see Proxies. The machine argument takes an id or a name, like everywhere else.

boxd.machines.proxies.create("my-machine", "api", 3000)
routes = boxd.machines.proxies.list("my-machine")
routes[0].port          # int — where traffic actually goes
routes[0].port_mode     # "locked" (you pinned it) | "auto" (detected for you)
routes[0].domain
routes[0].is_default

boxd.machines.proxies.set_port("my-machine", 3001, name="api")
boxd.machines.proxies.set_port("my-machine", "auto")   # default route, auto-detected
boxd.machines.proxies.delete("my-machine", "api")

name and port are both required on create — a named route is always pinned to a port. "auto" is only accepted for a machine’s default route, which is what set_port addresses when you leave name off.

Checkpoints

Per-machine save points, restored in place — see Checkpoints. They are deleted with the machine.

boxd.machines.checkpoints.create(id, "before-upgrade")   # machine must be running
points = boxd.machines.checkpoints.list(id)
points[0].status        # "pending" | "ready" | "failed"
points[0].available     # restorable right now
points[0].size_bytes
points[0].created_at

boxd.machines.checkpoints.restore(id, "before-upgrade")
boxd.machines.checkpoints.delete(id, "before-upgrade")

create returns while the capture is still "pending".

Snapshots

Reusable, named captures — see Snapshots. Boot one with machines.create(from_snapshot=...).

boxd.snapshots.create(machine_id, "golden")
snap = boxd.snapshots.get("golden")
boxd.snapshots.list()
boxd.snapshots.delete("golden")

Saving under an existing name adds a version. A Snapshot carries created_at (the first capture), updated_at (the most recent one), version, status, size_bytes, vcpu, memory_bytes and use_count. get, list and delete take an optional org=.

Disks

disk = boxd.disks.create("data", "10G")
boxd.disks.attach(disk.id, machine_id, "/mnt/data")
boxd.disks.attach(disk.id, machine_id, "/mnt/data", read_only=True)
boxd.disks.detach(disk.id, machine_id)
boxd.disks.list()
boxd.disks.delete(disk.id)

size takes a human string ("10G") or a byte count. A disk is always created writable; read-only is chosen per attachment. A disk can be attached to one machine at a time. status is "creating", "ready" or "destroyed" — it can only be attached once it is "ready". list() also returns each disk’s current attachments. You can mount a disk at create time instead, with volumes=[VolumeMount(...)].

Env vars and secrets

Two namespaces with identical methods — see Env vars & secrets. The difference is what comes back: an EnvVar has a readable value, a Secret has no value field at all.

boxd.env.set("MODE", "production", scope="all")
boxd.env.list()                    # [EnvVar(name, scope, value)]
boxd.env.delete("MODE", scope="all")

boxd.secrets.set("API_TOKEN", "s3cr3t", scope="shared")
boxd.secrets.list()                # [Secret(name, scope)] — no values
boxd.secrets.delete("API_TOKEN", scope="shared")

set, delete and move each hand back the server’s confirmation message as a str. Scope decides which machines a value reaches:

Scope	Applies to
`private`	only your own machines in that organization
`shared`	the organization’s shared machines
`all`	every machine in the organization

move changes the scope. It needs from_scope as well as to_scope, because the same name can exist in several scopes at once:

boxd.secrets.move("API_TOKEN", from_scope="private", to_scope="all")

It is a move between two places, not a field update, so calling it twice fails the second time. Env vars and secrets share one name space per scope, so an existing env var can block a secret moving into that scope, and vice versa. Pass org="acme" to any of these to work in an organization instead of your personal scope.

Organizations

orgs = boxd.orgs.list()
orgs[0].slug         # the org's unique key — pass this wherever a method takes `org`
orgs[0].name         # display label
orgs[0].is_admin
orgs[0].is_default   # your default org

API keys

key = boxd.api_keys.create("ci", org="acme")
key.api_key      # shown once — store it now
key.expires_at   # None = no expiry

boxd.api_keys.list()   # id, name, key_prefix, created_at, last_used_at, expires_at, org, kind
boxd.api_keys.delete(key.id)

Pass expires_in (seconds) for a key that expires. Every key belongs to exactly one organization: org names it, and omitting org uses your own. kind="member" (the default) acts as you within that organization; kind="org" is limited to the organization’s shared machines and requires an org admin to create.

create is the only time the raw key is returned. list shows the prefix only. Deleting a key takes effect immediately.

Account

from pathlib import Path

me = boxd.account.get()
me.user_id
me.display_name           # None falls back to user_id
me.pubkey_fingerprints
me.billing.max_vms              # your effective quota
me.billing.subscription_status  # None = never subscribed

boxd.account.link_ssh_key(Path.home().joinpath(".ssh/id_ed25519.pub").read_text())

cfg = boxd.account.config()
cfg.default_image
cfg.zone

link_ssh_key takes the verbatim contents of a .pub file and lets you SSH to your machines with it. Pass device_id= to keep one key per device — re-linking from the same device replaces that device’s key instead of accumulating stale ones.

Errors

from boxd import (
    BoxdError,               # base class — catch this to catch everything
    AuthenticationError,     # no usable credential, or it was rejected
    PermissionDeniedError,   # authenticated, but not allowed
    NotFoundError,           # no such resource
    ConflictError,           # already exists, or the resource is in the wrong state
    RateLimitError,          # quota or rate limit reached
    APIStatusError,          # any other error returned by the server
    APIConnectionError,      # the request never reached the server
)

try:
    boxd.machines.get("nope")
except NotFoundError:
    ...

Every error carries .message, .code (the canonical status name, e.g. "not_found") and .grpc_code (the numeric status code) for finer-grained handling:

import grpc

try:
    boxd.machines.create("my-machine")
except BoxdError as e:
    if e.grpc_code == grpc.StatusCode.RESOURCE_EXHAUSTED.value[0]:
        ...   # hit your quota — surface a 'wait or upgrade' path
    raise

Update notifications

The SDK prints a one-time note to stderr if a newer release is available:

A new version of boxd is available (v0.2.0, you have v0.1.9). Update with:
  pip install --upgrade boxd

It fires at most once per process and never causes a request to fail. The installed version is available as boxd.__version__.

Getting started

Cloud dev boxes

Preview environments

Agents on boxd

Organizations

Integrations

How it works

Reference

Install

Quick start

The client

Sync and async

Authentication

Inside a machine

Machines

Creating

The `Machine` record

Exec

Logs

Files

Ports

Proxies

Checkpoints

Snapshots

Disks

Env vars and secrets

Organizations

API keys

Account

Errors

Update notifications

Reference

CLI

TypeScript SDK

​Install

​Quick start

​The client

​Sync and async

​Authentication

​Inside a machine

​Machines

​Creating

​The Machine record

​Exec

​Logs

​Files

​Ports

​Proxies

​Checkpoints

​Snapshots

​Disks

​Env vars and secrets

​Organizations

​API keys

​Account

​Errors

​Update notifications

​Reference

CLI

TypeScript SDK

Install

Quick start

The client

Sync and async

Authentication

Inside a machine

Machines

Creating

The `Machine` record

Exec

Logs

Files

Ports

Proxies

Checkpoints

Snapshots

Disks

Env vars and secrets

Organizations

API keys

Account

Errors

Update notifications

Reference