CLI (external)

The boxd CLI lets you manage machines from your local terminal without SSH keys. Recommended for automation and coding agents. The surface is a nested tree. Top-level groups: machine (alias m), snapshots (alias snap), auth, manage, env, config, plus docs / completions / version. remove is the canonical delete verb everywhere (alias rm); common aliases are ls (list), info (get), ssh (connect). boxd new and boxd connect also exist at the top level as shortcuts for boxd machine new / boxd machine connect.

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.

Install

curl -fsSL https://boxd.sh/downloads/install.sh | sh

Installs the boxd binary to ~/.local/bin/boxd (macOS arm64, Linux x86_64/arm64). The client utilities — the bridge that brings your clipboard, local files, and browser into a machine (macOS Apple Silicon for now) — are built into the same binary; turn them on with boxd config set client-utils.enable true. It also drops a set of agent skills into ~/.claude/skills/ — boxd-cli for everyday CLI driving, plus setup skills that wire boxd into a GitHub repo end-to-end via webhooks. Re-run the installer any time to upgrade the binary and the skills together. (Claude Code only for now — see the Skills page if you want them on another platform.)

Authentication

boxd auth login                # opens browser for one-time device login
boxd auth logout               # remove stored credentials
boxd auth                      # show your identity and the orgs you belong to

Any command that needs auth auto-starts the login flow if no credentials are found. You can also authenticate via token:

boxd --token=<TOKEN> machine list      # pass token directly
BOXD_TOKEN=<TOKEN> boxd machine list   # or via env var

API keys

For CI pipelines, scripts, or agent integrations where the browser login flow isn’t an option, mint long-lived API keys under boxd auth keys. The raw value is shown only once at creation time.

boxd auth keys create NAME                            # mint a new key, raw value to stdout
boxd auth keys create NAME --expires-in-secs=86400    # with an expiry (1 day in this example)
boxd auth keys create NAME --org myorg                # fence the key to a specific org
boxd auth keys create NAME --kind org                 # userless service credential (org admin only)
boxd auth keys list                                   # id, name, prefix, last-used, expires (alias: ls)
boxd auth keys remove ID                              # revoke a key (alias: rm)

Every key is fenced to one org — it never grants account-wide access. Without --org, the key is fenced to your active org context. --kind member (default) acts as you within that org; --kind org is a userless service credential limited to the org’s shared machines (requires org admin). keys create writes the raw bxd_… value to stdout; the warning + id + expiry go to stderr. To put it straight into a GitHub secret without copy/paste:

KEY=$(boxd auth keys create "gh-actions deploy owner/repo")
gh secret set BOXD_API_KEY --repo owner/repo --body "$KEY"

The key never lands in shell history or scrollback. --json mode is also available for scripting:

Command	JSON shape
`auth keys create --json`	`{"id", "api_key", "expires_at"}` (`expires_at: 0` = no expiry)
`auth keys list --json`	`[{"id", "name", "prefix", "last_used", "expires"}, …]`

Managing machines

boxd machine new myapp                              # create a machine (~2s boot)
boxd machine new                                    # auto-named
boxd machine new myapp --auto-suspend-timeout=60    # idle secs before auto-suspend (0 disables)
boxd machine new myapp --shared                     # in an org context: shared with the whole org from birth
boxd machine list                                   # list your machines (alias: ls)
boxd machine get myapp                              # detailed info (status, image, auto-suspend; alias: info)
boxd machine fork myapp myapp-v2                    # fork with a full disk copy
boxd machine fork myapp --auto-suspend-timeout=0    # fork with auto-suspend disabled
boxd machine fork shared-vm --shared                # keep a fork of a shared machine shared (default: private to you)
boxd machine rename myapp myapp2 -y                 # rename (reboots to apply the hostname unless stopped)
boxd machine remove myapp -y                        # destroy (requires -y or --confirm; alias: rm)

boxd new myapp and boxd m ls are the top-level / short forms. machine new folds in fork (--fork) and snapshot restore (--from-snapshot):

boxd machine new myapp-v2 --fork myapp              # same as `machine fork myapp myapp-v2`
boxd machine new fresh --from-snapshot my-workspace # create from a snapshot (fast; restores memory + disk)

See Suspend & resume for how the idle timers work. All commands accept --json.

State control

Three categories of state transition, all boxd machine <verb> <machine>:

boxd machine start myapp       # start a stopped machine
boxd machine stop myapp        # stop (disk persists; running processes lost)
boxd machine pause myapp       # standby (warm — memory preserved, sub-ms resume)
boxd machine resume myapp      # resume a paused machine
boxd machine hibernate myapp   # cold snapshot to disk now (frees host RAM)
boxd machine wake myapp        # wake a hibernated machine
boxd machine reboot myapp      # reboot (cold — memory lost, ~2s)

pause / resume: warm. Freezes the VMM process, keeps memory, running processes, and open sockets intact. Resume is sub-millisecond. Same mechanism as auto-suspend, but user-triggered. Status becomes standby.
reboot / stop + start: cold. Kills the VMM process. Memory lost, takes ~2s.

Use pause for cost savings without losing state. Use reboot when you need a cold kernel/config restart.

Running commands

boxd machine exec myapp -- uname -a                        # run a command
boxd machine exec myapp -- 'cd /app && npm start'          # shell constructs work
boxd machine exec myapp -e API_KEY=secret -e DEBUG=1 -- CMD  # env vars
boxd machine exec myapp --timeout 30 -- CMD                # timeout
boxd machine exec myapp --tty -- htop                      # allocate a pseudo-TTY (for interactive tools)
boxd machine exec myapp --json -- echo hello               # JSON: {"output":"hello\n","exit_code":0}

Exit codes are forwarded — if the remote command exits 42, boxd machine exec exits 42. The remote command’s stdout and stderr are surfaced separately on the local side, so shell redirects work as you’d expect:

boxd machine exec myapp -- gcc -v 2>/dev/null              # drop the version banner (it's on stderr)
boxd machine exec myapp -- cargo build 2>build.log         # only warnings/errors land in build.log

PTY execs (--tty) are an exception — the kernel TTY layer merges stderr into stdout (that’s how terminals work), so everything arrives on local stdout and 2> filters won’t separate them.

The -- separator is required between the machine name and the command. Without it, tokens like sudo or apt get parsed as flags and the command errors out.

Interactive access

boxd connect drops you straight into an interactive shell on the machine over the boxd API — no SSH config, no host keys, no extra credentials. Auto-resumes paused or hibernated machines on demand. Exit codes forward; type exit or Ctrl-D to come back to your local shell.

boxd connect myapp             # drops you into a shell (top-level shortcut)
boxd machine connect myapp     # the full path
boxd machine ssh myapp         # `ssh` is the alias of connect

Requires an interactive terminal — connect refuses to run in scripts, pipes, or other non-TTY contexts. For automation, use boxd machine exec instead:

boxd machine exec myapp -- uptime    # one-shot, scriptable

Editor & SSH integration

The CLI keeps a managed block of Host entries in ~/.ssh/config automatically — every machine new, fork, list, remove, and rename refreshes it, so your SSH config stays in sync as machines come and go. There’s no separate command to run. After the first sync, <vmname>.boxd is reachable to plain ssh, scp, rsync, Cursor / VS Code Remote-SSH, JetBrains Gateway, Zed Remote, etc. — without per-machine hand-rolling:

ssh myapp.boxd                                      # plain SSH (alias carries HostName + Port)
cursor --remote ssh-remote+myapp.boxd /home/boxd    # Cursor (Remote-SSH)
code   --remote ssh-remote+myapp.boxd /home/boxd    # VS Code
# JetBrains Gateway / Zed: pick `myapp.boxd` from their host picker

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, and a User line. The <vmname>.boxd alias bakes the port in for you — connecting to the bare <vmname>.boxd.sh hostname (port 22) instead reaches the proxy, not the machine (the old ssh boxd.sh management shell there is retired — use this CLI). The managed block is bracketed with # BEGIN boxd / # END boxd; nothing outside the markers is ever modified.

Copying files

Paths after : are relative to /home/boxd unless starting with /. Uploads stream automatically — no inherent file-size cap.

boxd machine cp ./local.txt myapp:/home/boxd/remote.txt    # upload
boxd machine cp myapp:/home/boxd/remote.txt ./local.txt    # download
boxd machine cp myapp:/path/file -                         # download to stdout
echo data | boxd machine cp - myapp:/path/file             # upload from stdin
boxd machine cp -r ./dir myapp:dir                         # recursive

Proxy management

Every machine gets https://name.boxd.sh forwarding to its default port. Publish more ports — HTTPS subdomains or raw TCP/UDP forwards — all under boxd machine proxy.

boxd machine proxy list --vm myapp                       # list published ports (alias: ls)
boxd machine proxy add api --vm myapp --port 3001        # HTTPS subdomain: api.myapp.boxd.sh → 3001
boxd machine proxy set-port --vm myapp --port 3000       # change the default proxy's target port
boxd machine proxy set-port --vm myapp --port auto       # auto-detect the listening port
boxd machine proxy remove api --vm myapp                 # remove a subdomain proxy (alias: rm)

Subdomain proxies are HTTPS-only. To expose a database, an SSH daemon, or any non-HTTP service, use a raw port forward (below).

Exposing raw TCP/UDP ports

Raw forwards live under the same machine proxy group — pass --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 name.boxd.sh endpoint at that port. See Port forwarding for the concept.

boxd machine proxy add --vm myapp --port 5432 --raw            # forward a public port -> :5432 (TCP)
boxd machine proxy add --vm myapp --port 9999 --raw --udp      # UDP instead
boxd machine proxy add --vm myapp --port 7777 --raw --tcp --udp # both protocols on one allocated public port
boxd machine proxy list --vm myapp                            # raw forwards show as kind tcp/udp
boxd machine proxy remove 5432 --vm myapp                     # remove a raw forward by its machine port

Up to 3 raw forwards per machine. Re-adding a port you already forwarded keeps the same public port and just updates the protocol set. Forwards are owner-only and removed automatically when the machine is destroyed.

Snapshots

A snapshot captures a running machine’s memory + disk at a moment in time, replicated across a few workers. Create a machine from it near-instantly with machine new --from-snapshot.

boxd snapshots save myapp my-workspace              # save memory + disk as a named snapshot (machine keeps running)
boxd snapshots list                                 # name, version, status, size, used (alias: ls)
boxd snapshots remove my-workspace -y               # delete a snapshot and its replicas (alias: rm)
boxd snap save myapp my-workspace                   # `snap` is the short alias

Re-saving an existing name captures a new version (latest wins). Snapshots are fenced to the org context that created them and never cross an org boundary.

Checkpoints

A checkpoint captures a running machine’s memory + disk held on the machine’s own worker, restorable in place (the machine reboots into that exact state — same name, URL, and ports). Unlike snapshots they’re per-machine, not replicated, and never become a reusable image — they live and die with the machine. Use them as quick “save points” before a risky change.

boxd machine checkpoint save myapp before-migration    # capture memory + disk (machine keeps running)
boxd machine checkpoint list myapp                     # name, status, size, created, available (alias: ls)
boxd machine checkpoint restore myapp before-migration # reboot the machine into the checkpoint (-y to skip confirm)
boxd machine checkpoint remove myapp before-migration  # delete a checkpoint (-y; alias: rm)

Up to 10 checkpoints per machine. available: no means the checkpoint’s worker is no longer the machine’s worker (e.g. after a migration) — it can’t be restored until they line up again.

Integrations

Connect third-party accounts — GitHub, Linear, and Slack — under boxd manage integrations, and every personal machine in that org can use them. See Integrations for the full model.

boxd manage integrations                       # list connected integrations + what you can connect (alias: integ; ls)
boxd manage integrations connect linear        # connect via browser OAuth — prints a URL, polls until you approve
boxd manage integrations disconnect linear     # revoke at the provider + remove from boxd
boxd manage integrations mcp linear            # install Linear's MCP into all agents (claude, codex, opencode)
boxd manage integrations mcp slack claude      # ...or only specific agents
boxd manage integrations mcp linear --disable  # remove the MCP from every agent
boxd manage integrations --shared connect slack # connect the ORG's shared credential (org admin)

connect prints an authorize URL for you to open in a browser — a human has to approve it. Integrations are fenced to one org: your own connection serves your private machines in the active org; --shared addresses the org’s connection for its shared machines (admin only).

Env vars & secrets

Set environment variables and secrets once; boxd injects them into every machine you own in that org. Plain vars are cleartext and readable back; --secret seals a value at rest (write-only). See Env vars & secrets for the full model (scopes, naming, injection).

boxd env set DATABASE_URL postgres://…   # cleartext env var
boxd env set OPENAI_API_KEY sk-… --secret # sealed, write-only — never readable back
boxd env list                            # NAME / VALUE / SCOPE — secrets show (sealed) (alias: ls)
boxd env remove DATABASE_URL             # delete (alias: rm; --scope disambiguates in an org context)
boxd env scope OPENAI_API_KEY shared --from private  # move a secret to another org scope (value preserved)

To put a literal .env file on one machine (rather than an account-wide var), use boxd env push:

boxd env push myapp --file .env --dest ~/myapp/.env   # upload + chmod 600

Billing

Every machine is 2 vCPU / 8 GB RAM / 100 GB disk, billed by usage — there are no fixed plans or shapes to pick. Your balance, usage, and payment live under boxd manage billing.

boxd manage billing              # your (or the active org's) balance and usage
boxd manage billing --open       # open the billing portal in your browser

See Pricing for the rate card.

Organizations

If you belong to an organization, your active context decides which org a new machine is billed to and which machines list and connect see. Sharing a machine opens it to every member of the org.

boxd auth                        # identity + the orgs you belong to (active context marked)
boxd auth switch acme            # work in the "acme" org context (multi-word names need no quotes)
boxd auth switch personal        # back to your personal context
boxd machine share myapp         # share a machine with the whole org (every member can reach it)
boxd machine unshare myapp       # stop sharing — private to you again (org keeps paying)

The active org context is a per-device selection. boxd auth switch writes it locally; it is not synced to the web console or your other devices — each surface keeps its own. personal = your default 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 birth.
boxd manage billing follows the active context — in an org it shows the org’s balance and usage.
Share / unshare is owner-only. Any member can connect to a shared machine; a private machine (personal or org-billed) is reachable only by its owner.
An org has three roles: owner, admin, and member. Owners and admins invite and remove members at /app/organizations — see Organizations.

Sharing a machine wipes its in-VM agent logins (Claude Code, Codex, OpenCode) the instant it goes shared, so a teammate with a shell can never read your personal tokens. Unsharing restores Claude automatically; Codex/OpenCode need a one-time re-login. Forking a shared machine gives you a private fork with your logins intact. See Share a VM for the full handoff.

Per-machine settings

Auto-suspend and auto-hibernate timeouts live under boxd machine config (you can also set them at creation with --auto-suspend-timeout / --auto-hibernate-timeout).

boxd machine config list myapp                        # all settings for a machine
boxd machine config get myapp auto-suspend.timeout    # read one
boxd machine config set myapp auto-suspend.timeout 300    # suspend after 5 min idle (0 = off)
boxd machine config set myapp auto-hibernate.timeout 0    # never hibernate

CLI settings

boxd config persists laptop-side CLI settings (kept in config.toml).

boxd config list                              # api-url, client-utils.enable
boxd config get api-url                       # read one
boxd config set api-url https://boxd.sh       # persist the API server (flag/env still override)
boxd config set client-utils.enable true      # enable the clipboard/files/browser bridge for this device

Shell completions

Tab-completes commands, flags, and your machine/snapshot/org/proxy/key names (fetched live). Set up automatically by the installer and on boxd auth login; to (re)install manually:

boxd completions --install       # auto-detects your shell, idempotent
boxd completions zsh             # or print the raw script yourself

Open the docs

boxd docs                        # opens https://docs.boxd.sh in your browser

Global flags

Flag	Description
`--json`	Output as JSON (the only visible global besides `--help`)
`--api-url` / `BOXD_API_URL`	API server URL (hidden; default `https://boxd.sh`)
`--token` / `BOXD_TOKEN`	Auth token, overrides stored credentials (hidden)
`--org`	Run one invocation in a specific org context (hidden; persist with `boxd auth switch`)

Getting started

Cloud dev boxes

Preview environments

Agents on boxd

Organizations

Integrations

How it works

Reference

CLI (external)

Install

Authentication

API keys

Managing machines

State control

Running commands

Interactive access

Editor & SSH integration

Copying files

Proxy management

Exposing raw TCP/UDP ports

Snapshots

Checkpoints

Integrations

Env vars & secrets

Billing

Organizations

Per-machine settings

CLI settings

Shell completions

Open the docs

Global flags

​Install

​Authentication

​API keys

​Managing machines

​State control

​Running commands

​Interactive access

​Editor & SSH integration

​Copying files

​Proxy management

​Exposing raw TCP/UDP ports

​Snapshots

​Checkpoints

​Integrations

​Env vars & secrets

​Billing

​Organizations

​Per-machine settings

​CLI settings

​Shell completions

​Open the docs

​Global flags

Install

Authentication

API keys

Managing machines

State control

Running commands

Interactive access

Editor & SSH integration

Copying files

Proxy management

Exposing raw TCP/UDP ports

Snapshots

Checkpoints

Integrations

Env vars & secrets

Billing

Organizations

Per-machine settings

CLI settings

Shell completions

Open the docs

Global flags