--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.
Managing machines
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):
--new-only:
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, allboxd 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 assuspended.resumefails on a hibernated machine, so usewakethere. - 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.
pause to save cost without losing state. Use reboot when you need a cold restart.
Running commands
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:
--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 ofHost 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:
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:
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.--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 getshttps://<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.
Custom domains
Bring your own domain instead of<machine>.boxd.sh. See Custom domains for the full walkthrough (DNS records, confirmation step, gotchas).
--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 samemachine 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.
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 withmachine new --from-snapshot, and it resumes with its processes already running.
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.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.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 therun 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.
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).
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 underboxd 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 usageadds vCPU-hours and RAM and disk GiB-hours.manage usagedefaults to the last 28 days. - Windows.
--sinceand--untiltake 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, andmanage billing activityis what was actually charged. - Deleted machines. They stay in
manage usage, andmachine usagefinds 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.
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 machineslist 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 newcreates a machine billed to the org but private to you. Add--sharedto make it visible to the whole org from creation. boxd manage billingandboxd manage usagefollow 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
connectto 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.
boxd auth org and boxd teams, the same operations the console’s Organization page offers:
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.
--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.
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 underboxd 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).