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, domains, 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+.

Installation

pip install boxd

uv add boxd

The SDK prints a one-time note on stderr when a newer release is available. It never causes a request to fail. The installed version is available as boxd.__version__.

Authentication

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

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, with neither an API key nor 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.

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`	none
`token`	`BOXD_TOKEN`	none
`base_url`	`BOXD_BASE_URL` (or the deprecated `BOXD_API_URL`)	`https://boxd.sh:9443`
`timeout`	none	60 seconds
`max_retries`	none	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, because 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. Switching is await and an import rather than a rewrite. The streaming surfaces differ in shape, since stream_exec returns an AsyncExecStream you drive with async for and awaited write/resize calls, and logs is an async generator.

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

Commands

Every call is boxd.<namespace>.<verb>(...), and nine namespaces hold the whole surface:

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

Quick start

The whole loop in one example, create through destroy:

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 rather than a handle, and every operation takes the machine id (or name) as its first argument: boxd.<resource>.<verb>(id, ...).

Machines

Create, inspect, and control machines. The sub-namespaces boxd.machines.files, .ports, .proxies, .checkpoints, and .backups are covered further down in this section.

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, and hibernate 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_networks(id, ["backend"])          # replaces the whole set
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 rather than once it is usable. Call wait_until_ready before doing anything that depends on it running, and especially before forking it again. It polls for up to 90 seconds by default (timeout=, poll_interval=, both in seconds) and raises the builtin TimeoutError when the deadline passes.

Creating machines

boxd.machines.create(
    "builder",
    image="ubuntu:24.04",
    env={"API_URL": "https://example.com"},
    cmd=["/usr/local/bin/start"],
    restart_policy="always",          # "always" | "never"
    networks=["backend", "cache"],    # east-west reachability; see below
    isolated=False,                   # sandbox; immutable after creation
    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, with no config object. Every one is optional, and create() boots the default image at the default size. fork(source, name) takes the same sizing and lifecycle keywords plus shared, networks, and isolated, and anything you leave out is inherited from the source, including its networks. isolated is a one-way flag on fork and on create(from_snapshot=...). A fork or restore of an isolated machine is always isolated, and passing isolated=True isolates a copy of a machine that wasn’t. There is no way to remove isolation from a copy, and no setter afterwards. 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, isolated, and the sizing keywords. Passing image, env, cmd, restart_policy, shared or networks alongside it raises ValueError rather than silently ignoring them. (networks are replayed from the snapshot; set them afterwards with set_networks.)

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

Networks

Two machines reach each other when they share at least one network, or when neither has any. Machines with no networks form the org’s default network, so naming a network opts a machine out of that pool. The same rule governs the <name>.boxd DNS name and exec / cp between machines, so what resolves is exactly what is reachable.

boxd.machines.set_networks(id, ["backend", "cache"])   # → the set now in effect
boxd.machines.set_networks(id, [])                     # → the default network
machine.networking.networks, machine.networking.isolated

set_networks replaces the whole set rather than merging, and [] is a real destination, the default network, rather than a no-op. Networks are labels you pick, with nothing to create first, and they never cross an organization. Changes take effect immediately. isolated sandboxes a machine. It never joins the default network and is never a peer of another isolated machine, and boxd strips the in-VM boxd CLI, the metadata endpoint, and your integrations from it. An isolated machine with no networks therefore has no peers at all, and set_networks is the only lever it has. It is fixed at creation, with no setter. Outbound internet and inbound SSH/HTTPS are unaffected. See Sandboxes.

The `Machine` object

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.networking.networks   # list[str]: empty = the org's default network
machine.networking.isolated   # set at creation; a fork always inherits it

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.access.desktop_url      # its live Desktop view in the console
machine.access.custom_domains   # list[CustomDomain] bound to this machine

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, and shared says whether your teammates can see it. A private machine can still be org-billed, so org set with shared=False is normal rather than a contradiction. See VM sharing. 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, while a string is passed through as written. timeout is in seconds and gives up on the call, though 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()))

Set cols/rows for anything that draws to the terminal, since an unset size gives the PTY zero geometry and leaves the fallback to the program. 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.

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, and 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, and "both" shares one public port across TCP and UDP.

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, because 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".

Backups

Off-machine disk backups for disaster recovery, on demand or on a schedule. See Disaster recovery. Restoring one rewrites the disk only, not memory or running state.

backup_id = boxd.machines.backups.trigger(id)   # back up now, returns the new backup id

boxd.machines.backups.schedule_set(id, interval_secs=86400, retention_secs=30 * 86400)
# or a wall-clock cron schedule instead of a fixed interval:
boxd.machines.backups.schedule_set(id, cron="0 3 * * *", retention_secs=30 * 86400)

schedule = boxd.machines.backups.schedule_get(id)   # None when there's no schedule

backups = boxd.machines.backups.list(id)
backups[0].status        # "pending" | "ready" | "dedup" | "failed"
backups[0].size_bytes
backups[0].created_at

boxd.machines.backups.restore(id, backups[0].id)   # destructive, in-place
boxd.machines.backups.delete(id, backups[0].id)
boxd.machines.backups.schedule_clear(id)

Pass exactly one of interval_secs or cron to schedule_set; a schedule can’t fire more often than every 15 minutes either way. trigger is independent of the schedule and runs one capture at a time per machine. delete is refused for a backup still being captured or one a newer "dedup" entry still points at; a "dedup" backup restores the same as a "ready" one.

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, and read-only is chosen per attachment. A disk can be attached to one machine at a time. status is "creating", "ready" or "destroyed", and 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 rather than 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.

Egress

Two controls, both enforced outside the machine. See Egress control. A per-machine allowlist of what it may reach. Each call replaces the whole set; [] clears it:

boxd.machines.set_egress_allow(id, ["api.stripe.com", "*.npmjs.org", "203.0.113.0/24"])
boxd.machines.get(id).egress_allow   # list[str], empty = unrestricted
boxd.machines.set_egress_allow(id, [])

A secret bound to the hosts it may be sent to. The machine holds a bxds_… placeholder; the real value is substituted into requests to those hosts on the way out. domains is the full desired set, and setting the secret again without it makes it a plain secret:

boxd.secrets.set("STRIPE_KEY", "sk_live_...", scope="all", domains=["api.stripe.com"])
boxd.secrets.list()   # [Secret(name, scope, domains)]

Domains

Bring your own domain instead of name.boxd.sh. create binds the domain and starts verification immediately, so call it only once the DNS records are actually in place. The records to set (an A record plus a wildcard CNAME) and the verification flow are covered in Custom domains.

d = boxd.domains.create("app.example.com", machine.id)
d.status         # "pending" | "active"
d.last_error     # empty when healthy

boxd.domains.list()
boxd.domains.delete("app.example.com")

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

Wildcard domain

A wildcard domain for the whole org: see Custom domains. Setting or clearing requires org admin, and any member can read it.

domain = boxd.orgs.set_domain("acme", "preview.mysaas.com")   # call only once NS delegation is live
domain.status       # "pending" | "active"

boxd.orgs.get_domain("acme")     # None if unset
boxd.orgs.clear_domain("acme")

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, while 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, and deleting a key takes effect immediately.Key management itself needs a credential from an interactive login (the token boxd auth login stores, or BOXD_TOKEN). A client authenticated with an API key, or running on in-VM auth, gets PermissionDeniedError from api_keys.*, so an API key can never mint more keys.

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, so re-linking from the same device replaces that device’s key instead of accumulating stale ones. Like key management, link_ssh_key requires an interactive-login credential rather than an API key.

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:
    ...

Errors returned by the server carry .message, .code (the canonical status name, e.g. "not_found") and .grpc_code (the numeric status code) for finer-grained handling. Errors raised client-side, like an exec timeout, leave .code and .grpc_code as None:

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

Getting started

Guides

Integrations & automations

Use cases

References

Installation

Authentication

Inside a machine

The client

Sync and async

Commands

Quick start

Machines

Creating machines

Networks

The `Machine` object

Exec

Files

Ports

Proxies

Checkpoints

Backups

Snapshots

Disks

Env vars and secrets

Egress

Domains

Organizations

Wildcard domain

API keys

Account

Errors

​Installation

​Authentication

​Inside a machine

​The client

​Sync and async

​Commands

​Quick start

​Machines

​Creating machines

​Networks

​The Machine object

​Exec

​Files

​Ports

​Proxies

​Checkpoints

​Backups

​Snapshots

​Disks

​Env vars and secrets

​Egress

​Domains

​Organizations

​Wildcard domain

​API keys

​Account

​Errors

Installation

Authentication

Inside a machine

The client

Sync and async

Commands

Quick start

Machines

Creating machines

Networks

The `Machine` object

Exec

Files

Ports

Proxies

Checkpoints

Backups

Snapshots

Disks

Env vars and secrets

Egress

Domains

Organizations

Wildcard domain

API keys

Account

Errors