Internal CLI

Every machine has the boxd command pre-installed. Authentication is automatic — no SSH keys or tokens needed. This lets agents and scripts running inside a machine manage other machines directly. Like the laptop CLI, the surface is a nested tree: machine (alias m), snapshots (alias snap), manage, env, local, plus info for the current machine and top-level new / connect shortcuts. There’s no auth or config group — auth is automatic, and CLI settings live on the laptop. remove is the canonical delete verb (alias rm).

State-changing and destructive verbs require an explicit other machine — you can’t stop, reboot, or destroy the machine you’re currently inside.

Commands

boxd info                                   # current machine info
boxd machine list                           # list all your machines (alias: m ls)
boxd machine new NAME                        # create a machine
boxd machine fork                            # fork the current machine
boxd machine fork SOURCE --name NAME         # fork a specific machine
boxd machine get NAME                        # a machine's details (alias: info)
boxd machine reboot NAME                     # reboot another machine (cold — memory lost, ~2s)
boxd machine pause NAME                      # pause another machine (warm — memory preserved, sub-ms resume)
boxd machine resume NAME                     # resume a paused machine
boxd machine config set auto-suspend.timeout SECS --vm NAME   # suspend after SECS idle (0 = off)
boxd machine remove NAME -y                   # destroy another machine (cannot destroy the current one)
boxd machine exec NAME -- CMD                 # run a command in another machine
boxd connect NAME                             # interactive shell in another machine
boxd machine cp ./file.txt NAME:path          # upload a file to another machine
boxd machine cp NAME:path ./local             # download a file from another machine
boxd machine expose PORT                       # expose a raw TCP port on THIS machine
boxd machine expose NAME PORT                  # ...or on another machine (--udp / --tcp --udp; --remove; --list)
boxd machine fork SOURCE --shared              # keep a fork of a shared machine shared (default: private to you)
boxd machine share NAME                        # share a machine with the whole org (every member can reach it)
boxd machine unshare NAME                      # stop sharing — private to you again (org keeps paying)
boxd manage integrations                       # list integrations wired into this machine (alias: integ)
boxd manage integrations connect linear        # connect an integration (prints a browser URL to approve)
boxd manage integrations disconnect linear     # disconnect an integration
boxd manage integrations mcp linear            # install an integration's MCP into agents (--disable to remove)
boxd manage billing                            # balance, usage, quota (upgrades happen on your laptop, not in a machine)

Aliases: list/ls, remove/rm, connect/ssh, get/info. All commands accept --json for structured output.

pause vs reboot

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: cold. Kills the VMM process and spawns a new one. Memory lost, takes ~2s.

If you belong to an organization, boxd machine share NAME makes a machine reachable by every member; boxd machine unshare NAME makes it private to you again. When a user asks to “make this machine public,” they mean share it with the org — the *.boxd.sh URL is already public. In-VM you’re always in the owner’s active org context; switching orgs is a laptop-side action (boxd auth switch).

Sharing wipes the machine’s in-VM agent credentials (~/.claude/.credentials.json, ~/.codex/auth.json, ~/.local/share/opencode/auth.json) the instant it goes shared — so do not boxd machine share the machine you’re working in, or you’ll be logged out mid-task. Share a different idle machine, or make it the last step and re-authenticate afterward. Unsharing restores the Claude login automatically; forking a shared machine gives a private fork with logins intact. See Share a VM.

Connected integrations

boxd manage integrations (no subcommand) is the live source of truth for which external accounts the owner has wired into this machine, how to use each, and what else can still be connected. Run it rather than guessing; new integrations appear automatically.

boxd manage integrations                      # what's connected + how to use it, + what you can connect (--json for agents)
boxd manage integrations connect linear       # connect from here — prints a URL to approve in any browser
boxd manage integrations disconnect linear    # disconnect
boxd manage integrations mcp linear           # install Linear's MCP into agents (claude/codex/opencode)

Each connected integration lists its access methods tagged by kind — an env var + API endpoint (graphql/api), a CLI (cli), an MCP server (mcp), or git credentials (git). For example, a connected Linear exposes LINEAR_ACCESS_TOKEN for its GraphQL API, and Slack exposes SLACK_BOT_TOKEN / SLACK_USER_TOKEN / SLACK_TEAM_ID. The output also lists anything available to connect with the exact connect command. Connecting acts on the owner’s personal + private machines; a human does the browser approval. See Integrations.

Env vars & secrets

Set environment variables and secrets that boxd injects into every machine you own. Env vars and secrets share one command — --secret selects the sealed, write-only store. See Env vars & secrets for scopes, naming, and how they’re injected.

boxd env set DATABASE_URL postgres://…        # cleartext env var (list/rm; alias ls/remove)
boxd env set OPENAI_API_KEY sk-… --secret     # sealed, write-only (list shows names only)
boxd env list                                 # NAME / VALUE / SCOPE — secrets show (sealed)
boxd env rm DATABASE_URL                       # remove an env var (--secret targets a secret)

Running commands in other machines

boxd machine exec other-vm -- uname -a
boxd machine exec other-vm -e KEY=VAL -- CMD          # env vars
boxd machine exec other-vm --timeout 30 -- CMD        # timeout

The remote command’s stdout and stderr are merged into a single output stream on this CLI. If you need to filter them separately (e.g. 2>/dev/null to drop warnings), either redirect inside the command ('cmd 2>/dev/null') or use the external CLI / SDK from outside the machine, which preserve the split.

Copying files between machines

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

boxd machine cp ./config.json backend:config.json               # upload
boxd machine cp backend:output.log ./output.log                 # download
boxd machine cp backend:/etc/nginx/nginx.conf ./nginx.conf      # absolute path

Proxy management

Defaults to the current machine when --vm is omitted.

boxd machine proxy list                # proxies for this machine
boxd machine proxy list --all          # proxies for all machines
boxd machine proxy add api --port 3001 # create a subdomain proxy
boxd machine proxy set-port --port 3000 # change the default proxy port
boxd machine proxy set-port --port auto # auto-detect the port
boxd machine proxy remove api          # remove a proxy (alias: rm)

Exposing raw TCP/UDP ports

Subdomain proxies route HTTPS only. To expose a database, an SSH daemon, or any non-HTTP service, boxd machine expose opens a raw TCP/UDP port on the machine’s public proxy, forwarded straight to a port inside. The public port is allocated from the 40000–60000 range; connect on name.boxd.sh at that port. See Port forwarding. In-VM, expose PORT defaults to the current machine; pass a name to expose another.

boxd machine expose 5432               # forward a public port -> :5432 on THIS machine (TCP)
boxd machine expose other-vm 5432      # ...or on another machine
boxd machine expose 9999 --udp         # UDP instead
boxd machine expose 7777 --tcp --udp   # both protocols on one allocated public port
boxd machine expose --list             # list all your exposed ports
boxd machine expose 5432 --remove      # remove a forward, freeing the public port

Up to 3 forwarded ports per machine; owner-only.

Local machine access

When client utilities are enabled on the user’s laptop (boxd config set client-utils.enable true), the internal CLI can access files and a browser on the user’s local machine:

boxd local ls                              # list user's home directory
boxd local ls Documents                    # relative to home
boxd local read ~/notes.txt                # read a local file
boxd local read ~/log.txt --tail=50        # last 50 lines
boxd local read ~/log.txt --head=20        # first 20 lines
boxd local read ~/log.txt --range=10:30    # lines 10-30
boxd local browser open                    # launch Chrome on the user's Mac
boxd local browser open --headless         # headless mode
boxd local browser info                    # status + CDP WebSocket URL
boxd local browser close                   # close the browser

These commands need the BOXD_PROXY_ENDPOINT and BOXD_DEVICE_ID environment variables, which boxd injects into the session automatically when the device you connect from has client utilities enabled.

How it works

The internal CLI is authenticated automatically — the machine you’re inside identifies you, so there is nothing to configure and no token to manage. It acts as the account that owns the machine.

Do NOT try to ssh name.boxd.sh from inside a machine — machines don’t have your SSH keys. Use the boxd CLI to run commands and move files between machines.

Reaching another machine’s services

To hit a running service on another of your machines directly over the private network, resolve it by name: inside any machine, <vmname>.boxd resolves to that machine’s private IP.

curl http://worker-1.boxd:8000/health     # call a sibling's API
psql -h db.boxd -U postgres                # connect to a sibling's database

Resolution is owner-scoped (only your own machines resolve) and works across workers. Only the bare <vmname>.boxd form resolves; everything else falls through to normal upstream DNS. See VM-to-VM networking.

Delegating work to agents

Claude Code is pre-installed in every machine. Start it non-interactively and capture the session ID for follow-ups:

RESULT=$(boxd machine exec myvm -- 'claude -p --output-format json "Build a Flask API on port 8000" --dangerously-skip-permissions < /dev/null 2>/dev/null')
SESSION_ID=$(echo "$RESULT" | jq -r .session_id)

# Follow up on the same session
boxd machine exec myvm -- "claude -p --resume $SESSION_ID \"Add a /health endpoint\" --dangerously-skip-permissions < /dev/null"

The session ID is the handoff mechanism between orchestrator, in-machine agent, and human user.

Getting started

Cloud dev boxes

Preview environments

Agents on boxd

Organizations

Integrations

How it works

Reference

Internal CLI

Commands

pause vs reboot

Connected integrations

Env vars & secrets

Running commands in other machines

Copying files between machines

Proxy management

Exposing raw TCP/UDP ports

Local machine access

How it works

Reaching another machine’s services

Delegating work to agents

​Commands

​pause vs reboot

​Organizations & sharing

​Connected integrations

​Env vars & secrets

​Running commands in other machines

​Copying files between machines

​Proxy management

​Exposing raw TCP/UDP ports

​Local machine access

​How it works

​Reaching another machine’s services

​Delegating work to agents

Commands

pause vs reboot

Organizations & sharing

Connected integrations

Env vars & secrets

Running commands in other machines

Copying files between machines

Proxy management

Exposing raw TCP/UDP ports

Local machine access

How it works

Reaching another machine’s services

Delegating work to agents