Skip to main content
Every machine operation is available from the CLI, and all commands accept --json for scripting. This page is the full reference for the CLI on your laptop. The in-machine CLI has a different command set, and the forms that only work inside a machine are marked as such.

The command tree

The surface is a nested tree. This is the full first level: The three shortcuts exist because creating, connecting, and listing are what you do all day: boxd new myapp and boxd machine new myapp are the same command. remove is the delete verb everywhere (alias rm), with one exception: a team is deleted with boxd teams destroy (alias rm). The common aliases are ls for list, info for machine get, and ssh for connect. On the laptop info exists only as that alias (boxd machine info myapp). A top-level boxd info exists only inside a machine.
boxd <cmd> --help is the always-current reference for flags and subcommands, straight from your installed binary. Running bare boxd in a terminal drops into an interactive REPL (boxd (org)>) where you type the same commands without the boxd prefix, with tab completion and arrow-key pickers for missing arguments.

Managing machines

Inside a machine, boxd machine remove --self deletes the machine it runs on, after a yes/no question. See Self-delete. boxd new myapp and boxd m ls are the top-level and short forms. machine new folds in forking (--fork) and creating from a snapshot (--from-snapshot):
See Suspend, resume, and hibernate for how the idle timers work, and Machine sizes for sizing. A fork and a machine created from a snapshot keep their source’s size, so passing a size there is an error. The size a machine gets when you name none is the org’s default:
The org can also set the bot protection that new machines start with, and whether their idle timers ignore outbound traffic. Setting a default changes your existing machines too (machines with bot protection off stay off), unless you pass --new-only:
How many machines the org may have at once is its machine limit. Any member can read it; the org’s owner can ask for more, with their login or an API key of theirs. Ask for the new total (above the current limit, at most 1000). One request is open at a time, and the owner gets an email when the limit changes:
With several regions, the limit applies in each region on its own, and manage machine-limit shows the machines in use in each. --json then adds "regions", one {"region","vm_count"} per region, and vm_count counts Frankfurt’s.

State control

Three categories of state transition, all boxd machine <verb> <machine>:
  • pause and resume. Warm. Memory, running processes, and open sockets stay intact, and resume is sub-millisecond. This is the same mechanism as auto-suspend, only user-triggered. Status becomes standby. The API and SDKs report the same state as suspended. resume fails on a hibernated machine, so use wake there.
  • hibernate and wake. Memory is written to disk and the machine gives up its RAM. Waking takes about 85ms.
  • reboot, and stop then start. Cold. Memory is lost and the restart takes about 2 seconds.
Use pause to save cost without losing state. Use reboot when you need a cold restart.

Running commands

Exit codes are forwarded, so a remote command that exits 42 makes boxd machine exec exit 42. The remote command’s stdout and stderr are surfaced separately on your laptop, so shell redirects work as you’d expect:
PTY execs (--tty) are the exception. The kernel TTY layer merges stderr into stdout, as terminals do, so everything arrives on stdout and 2> filters won’t separate them.
The -- separator between the machine name and the command is optional, since everything after the machine name is treated as the command. Put exec’s own flags (-e, --timeout, --tty) before the command, and use -- or quotes when your command starts with a dash.

Interactive access

boxd connect drops you straight into an interactive shell on the machine over the boxd API. It needs neither SSH config nor host keys, wakes a machine that is on standby or hibernated, and forwards exit codes. Type exit or Ctrl-D to come back to the shell on your laptop.
connect requires an interactive terminal and refuses to run in scripts, pipes, or other non-TTY contexts. For automation, use boxd machine exec instead:

Editor and SSH integration

The CLI keeps a managed block of Host entries in ~/.ssh/config automatically. boxd auth login writes it, every machine new, fork, list, rename, and remove refreshes it, and a background agent re-syncs it periodically, so your SSH config stays current as machines come and go. There is no separate command to run. After the first sync, <machine>.boxd is reachable to plain ssh, scp, rsync, Cursor / VS Code Remote-SSH, JetBrains Gateway, Zed Remote, and anything else that reads SSH config:
Each machine is reachable on a dedicated SSH port (10000-30000 range) on the shared proxy IP, so each stanza carries a HostName, a Port, a User, and a managed IdentityFile. The CLI also pre-trusts the proxy’s host key in ~/.ssh/known_hosts, so the first connect never prompts. Connecting to the bare <machine>.boxd.sh hostname on port 22 reaches the proxy rather than the machine, so always use the <machine>.boxd alias. The managed block is bracketed with # BEGIN boxd / # END boxd, and nothing outside the markers is ever modified. Machines in another region get a block of their own, with that region’s address, port and host key, under the alias <machine>.<region>.boxd:
Only a key linked to the machine’s owner, or to a member of its org while the machine is shared, gets past authentication on the machine’s port. Any other key is refused there, as an unknown key is.

Turn SSH off

A machine has SSH on unless you turn it off. With SSH off, nothing answers SSH for the machine, on its public address or on your org’s Tailscale or NetBird network: the connection closes before a single byte of SSH is sent. SSH sessions open to it are closed when you turn it off.
boxd connect, boxd machine exec, file copies and the console’s terminal go through the boxd API rather than SSH, so they keep working. The machine keeps its SSH port, so turning SSH back on brings back the same address and your ~/.ssh/config entry needs no change. A fork and a machine created from a snapshot keep their source’s setting unless you pass --ssh or --no-ssh. SSH can’t be turned back on from inside the machine.

Copying files

Paths after : are relative to /home/boxd unless starting with /. Uploads and downloads stream, and from the laptop they have no size cap.

Disks

A standalone disk outlives the machine it is attached to. See Disks for the model.
A machine can only mount a disk that lives on its own host, so to pair a disk with a new machine, attach it at creation and the machine is placed on the disk’s host:
Not available with --fork or --from-snapshot. Create the machine first, then disks attach. A disk lives in one region and attaches to machines there. boxd disks new data --size 10G --region nyc makes one in New York.

Proxy management

Every machine gets https://<machine>.boxd.sh forwarding to its default port. Publish more ports, either as HTTPS subdomain proxies or as raw port forwards, all under boxd machine proxy.
Subdomain proxies are HTTPS-only. To expose a database, an SSH daemon, or any non-HTTP service, use a raw port forward.

Custom domains

Bring your own domain instead of <machine>.boxd.sh. See Custom domains for the full walkthrough (DNS records, confirmation step, gotchas).
Org admins can delegate a wildcard to the whole org instead of binding machines one at a time:
With several regions, the org has one wildcard domain in each, delegated to that region’s nameservers. --region picks which, and manage domain get --region all lists them all. One region’s domain can’t be the same as, inside or around another’s, so use names side by side, such as preview.mysaas.com and preview-nyc.mysaas.com.

Raw TCP and UDP ports

Raw port forwards live under the same machine proxy group, selected with --raw. boxd opens a raw TCP or UDP port on the machine’s public proxy and forwards it straight to a port inside the machine, for anything that isn’t HTTP (databases, game servers, custom protocols). The public port is allocated for you. Connect on the machine’s existing <machine>.boxd.sh endpoint at that port. See Port forwarding for the concept.
Up to 3 raw port forwards per machine. Re-adding a port you already forwarded keeps the same public port and updates the protocol set. Raw port forwards are owner-only and removed automatically when the machine is deleted.

Snapshots

A snapshot captures a running machine’s memory and disk at a moment in time, replicated across a few hosts. Create a machine from it with machine new --from-snapshot, and it resumes with its processes already running.
Saving again under the same name replaces the version. New machines get the latest one, and older versions cannot be restored, so save under a new name to keep an old state. Snapshots are fenced to the org context that created them and never cross an org boundary. A snapshot lives in its machine’s region, and machines created from it start there.

Checkpoints

A checkpoint captures a running machine’s memory and disk on the machine’s own host, restorable in place: the machine reboots into that exact state with the same name, URL, and ports. Checkpoints are per-machine and live and die with the machine. Use a checkpoint as a quick save point before a risky change, and a snapshot to create new machines from.
Up to 10 checkpoints per machine. available: no means the checkpoint’s host is no longer the machine’s host (for example after a migration), so it can’t be restored until they line up again.

Backups

A backup uploads a machine’s disk to object storage, off the cluster, for disaster recovery. Backups are off by default and set per machine. Take one on demand, or set a schedule. Restoring is a full, in-place disk rewrite. See Disaster recovery for the full model.
A scheduled backup can’t fire more often than every 15 minutes. backup now is independent of the schedule and runs one capture at a time per machine. backup remove is refused for a backup still being captured, or one a newer unchanged-since backup still points at. An org can hand every new machine a schedule by default. Only machines created afterwards are affected:

Integrations

Over a hundred integrations (Linear, Slack, GitHub and more) are connected from the console’s Integrations page or with the run CLI inside a machine (run auth linear). See Connections for the model. From the laptop, boxd manage integrations lists what’s connected and connects any of them by name:

Desktop

boxd machine desktop prints the URL of a machine’s live desktop and opens it in your browser. The owner can open it, and so can any org member when the machine is shared. See Desktop.

Computer use

boxd machine computer works a machine’s desktop with screenshots, the mouse and the keyboard, for agents and scripts. The desktop starts on demand. See Computer use.
Coordinates are screen pixels from the top left. Inside a machine, leave out the name to act on that machine.

Env vars and secrets

Set environment variables and secrets once, and boxd injects them into the machines in the var’s scope. shared reaches the org’s shared machines, private reaches your own private machines in that org, and all reaches both. The default is shared when you are working in an org. Plain vars are cleartext and readable back. --secret seals a value at rest, write-only. See Env vars and secrets for the full model (scopes, naming, injection, host-bound secrets).
To put a literal .env file on one machine, rather than a scoped var, use boxd env push:
--file defaults to .env, --dest to the file’s name in the machine’s home directory, and --mode to 600.

Usage and billing

A machine is 2 vCPU / 8 GiB RAM / 100 GB disk by default (other sizes). Your balance and payment live under boxd manage billing, and what each machine cost under boxd manage usage.
manage billing activity lists the newest first and sums usage charges per day (UTC). It defaults to the last 28 days; --limit N or --all shows more rows, and --json lists every individual entry.
  • What you see. Time running, in standby, hibernated and stopped, and the cost. machine usage adds vCPU-hours and RAM and disk GiB-hours. manage usage defaults to the last 28 days.
  • Windows. --since and --until take a duration back from now (24h, 7d, 30d), a UTC date or time (2026-09-01, 2026-09-01T14:30Z), or unix seconds. A window spans at most 366 days.
  • Estimated costs. Usage is metered with a delay of up to 25 minutes. A cost marked (estimated) can still grow; one without it is final. Costs are priced at current rates, and manage billing activity is what was actually charged.
  • Deleted machines. They stay in manage usage, and machine usage finds one by its name or id. If several deleted machines had the same name, the command lists their ids so you can pick one.
  • Who can see it. Usage and billing activity are for org owners and admins.
Inside a machine, boxd machine usage works for that machine only and shows its own usage and cost. The other machines and the org-wide views are on your laptop. See boxd.sh/pricing for the rate card.

Organizations

Every account works inside an organization, and every user has a default org of their own. Your active context decides which org a new machine is billed to and which machines list and connect see. Switching context is covered in Org context. Sharing a machine opens it to every member of the org.
  • In an org context, boxd machine new creates a machine billed to the org but private to you. Add --shared to make it visible to the whole org from creation.
  • boxd manage billing and boxd manage usage follow the active context, so in an org they show the org’s balance and its machines’ usage.
  • Share and unshare are owner-only. Any member can connect to a shared machine. A private machine is reachable only by its owner.
  • An org has three roles: owner, admin, and member. See Organizations and teams for what each can do.
The org itself, its roster and its teams are managed under boxd auth org and boxd teams, the same operations the console’s Organization page offers:
Sharing a machine wipes the agent logins inside it (Claude Code, Codex, OpenCode) the instant it goes shared, so a colleague with a shell can never read your tokens. Unsharing restores Claude and Codex automatically, while OpenCode needs a one-time re-login. Forking a shared machine gives you a private fork with your logins intact. See Machine sharing for the full handoff.

Regions

Machines, snapshots and disks live in one region, Frankfurt (fra) or New York (nyc). Every org has both. Your account, API keys, env vars, secrets and billing work in every region. See Regions for the model.
Without --region, a command uses BOXD_REGION, then boxd config set region, then the org’s default region, then the closest region. --region all is for lists only (machine list, snapshots list, disks list, teams list, manage domain get), and a list of one region ends with a count of the rest, such as and 3 in nyc. A name that isn’t in the current region but is in another gets an error that repeats your command with --region set. Inside a machine, boxd info shows the machine’s region, and the in-machine boxd acts in that region only.

Networks

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 direct connections, the <machine>.boxd DNS name, and machine exec / cp between machines.
Networks are labels you pick, with nothing to create first, and they never cross an organization or a region. Changes take effect immediately, without a reboot. Set them at creation with machine new --networks, and edit them later from the machine’s Networking tab in the console as well.

Egress allowlist

Limit what a machine can reach on the internet. See Egress allowlist.
machine new --isolated sandboxes a machine. It never joins the default network and never reaches another isolated machine, and boxd removes everything that could reach into the rest of your org from it: the in-machine boxd CLI, the metadata endpoint, the run CLI and automations, the git and gh credential helpers, integrations, agent logins, the boxd skill, and the laptop bridge. Outbound internet (unless an egress allowlist is set), env vars in exec and SSH sessions, its HTTPS domain, and inbound SSH (unless you turn it off) still work. Isolation is fixed at creation and always inherited by forks and by machines created from a snapshot of it, while its --networks remain editable and are the only thing it can reach through. See Sandboxes.

Per-machine settings

The auto-suspend and auto-hibernate timeouts, whether the idle timers ignore outbound traffic, bot protection and SSH live under boxd machine config, as the keys auto-suspend.timeout, auto-hibernate.timeout, idle.ignore-outbound, bot-protection and ssh. You can also set the timeouts at creation with --auto-suspend-timeout and --auto-hibernate-timeout, and idle.ignore-outbound with --idle-ignore-outbound. The backup schedule keys (backups.period, backups.retention) live here too. See Backups. So does the delete-after timer, as the key delete-after.

CLI settings

boxd config persists laptop-side CLI settings (kept in config.toml).
Shell completions are covered in Installation.

Open the docs

Global flags