> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Internal CLI

> Manage machines from inside a machine using the pre-installed boxd command.

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](/reference/external-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`).

<Note>
  State-changing and destructive verbs require an **explicit other machine** — you can't stop, reboot, or destroy the machine you're currently inside.
</Note>

## Commands

```bash theme={"theme":"github-dark"}
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.

## Organizations & sharing

If you belong to an [organization](/organizations/overview), `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`).

<Warning>
  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](/organizations/share-a-vm).
</Warning>

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

```bash theme={"theme":"github-dark"}
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](/integrations/linear) exposes `LINEAR_ACCESS_TOKEN` for its GraphQL API, and [Slack](/integrations/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](/integrations/overview).

## 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](/reference/env-secrets) for scopes, naming, and how they're injected.

```bash theme={"theme":"github-dark"}
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

```bash theme={"theme":"github-dark"}
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
```

<Note>
  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.
</Note>

## Copying files between machines

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

```bash theme={"theme":"github-dark"}
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.

```bash theme={"theme":"github-dark"}
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](/how-it-works/port-forwarding).

In-VM, `expose PORT` defaults to the **current** machine; pass a name to expose another.

```bash theme={"theme":"github-dark"}
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](/reference/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:

```bash theme={"theme":"github-dark"}
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.

<Warning>
  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.
</Warning>

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

```bash theme={"theme":"github-dark"}
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](/how-it-works/vm-to-vm#reach-another-vm-over-the-network).

## Delegating work to agents

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

```bash theme={"theme":"github-dark"}
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.