Installation & updates
# Install (run once)
curl -fsSL https://box.ascii.dev/install | sh
# Check for and apply updates
box self-update
--no-update.
Global flags
These flags work with any command:
| Flag | Description |
|---|
--api-url <URL> | Override the API endpoint (env: BOX_API_URL) |
--json | Output machine-readable JSON instead of human text |
--no-update | Skip the automatic update check |
--json is enabled automatically whenever output is piped or redirected, so scripts get JSONL without passing the flag.
Wherever a command takes a box ID, two aliases also work: current (the last box created in this shell) and self (the box you are running inside, when using the CLI from within a box).
Shell completion
box completions <shell> prints a completion script for bash, zsh, fish, or PowerShell. It completes subcommands and your live box IDs (plus current and self), with a 15 second cache so repeated tabs are instant.
# bash: add to ~/.bashrc
eval "$(box completions bash)"
# zsh: add to ~/.zshrc, after compinit
eval "$(box completions zsh)"
# fish
box completions fish > ~/.config/fish/completions/box.fish
# PowerShell: add to $PROFILE
box completions powershell | Out-String | Invoke-Expression
Authentication
box onboard
Full onboarding flow: opens GitHub OAuth, authenticates, and saves your token.
box login [key]
Sign in with an existing API token, or start a browser sign-in flow if no key is given. GitHub is the default; Google and email also work.
box login
box login --google
box login --email you@example.com
box login box_abc123...
box logout
Sign out and clear the local token.
box status
Show API health, the signed-in account and plan, and the local config path.
Box lifecycle
box new
Create a new box.
box new [--ttl SECONDS]
box new --no-auto-stop
box new --env KEY=VALUE --env OTHER=VALUE
box new --no-env
| Flag | Default | Maximum |
|---|
--ttl | 3600 (1 hour) | 2592000 (30 days) |
--no-auto-stop | off | no automatic stop |
--env, -e | none | 100 variables, 64KB total |
--no-env | off | none |
--env sets per-box environment variables on top of your dashboard secrets; per-box values win on name conflicts. See Secrets & Setup.
--no-env creates a box that receives none of the secrets attached to your account, and confines the box to itself so it can’t act on your account or other boxes. Use it for boxes you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work. See Secrets & Setup.
Returns the box ID, IP, and initial state.
For a long uninterrupted workflow, disable auto-stop:
See Long-Running Tasks.
box list
List all your boxes with their current state and ID.
box extend <id>
Change the auto-stop timer for an existing Box.
box extend bx_f7k2q9hd --hours 12
box extend bx_f7k2q9hd --ttl 2592000
box extend bx_f7k2q9hd --no-auto-stop
--hours or --ttl for a timed extension. Use --no-auto-stop when the Box should keep running until you stop it yourself.
box info <id>
Get details for a specific box: state, IP, desktop availability, TTL remaining.
box stop <id>
Pause a running box. Creates a snapshot then stops billing. The box enters archiving → archived.
Snapshotting takes a moment. The box is not yet stopped when the command returns; poll box info to confirm archived state.
box resume <id>
Resume a stopped box from its last snapshot. The box is usable in a few seconds regardless of data size; remaining file content streams in the background. See Snapshots.
box resume bx_f7k2q9hd
box resume --no-env bx_f7k2q9hd
box stop).
Use --no-env to resume a stopped box after dropping your account secrets and scrubbing owner secrets inherited from the snapshot. This is one-way: the box stays no-env afterward.
Resume behaves like a server reboot: systemd services you enabled start again automatically. Processes you ran by hand (dev servers, background jobs, tunnels, desktop sessions) do not survive; restart them, or make them a systemd service.
box delete <id>
Permanently delete a box and all its data.
box fork <id>
Clone a box from its latest snapshot into a new independent box.
box fork bx_f7k2q9hd
box fork --no-env bx_f7k2q9hd
--no-env to fork into a no-env box. A fork of a no-env source is always no-env.
box events <id>
Read a Box’s persisted lifecycle and agent chat events. Add --follow to keep polling for new events.
box events bx_f7k2q9hd
box events bx_f7k2q9hd --follow
| Flag | Description |
|---|
--follow | Continue polling and printing new events until interrupted |
box interrupt <id>
Interrupt the currently running agent work in a Box.
box interrupt bx_f7k2q9hd
Access
box ssh <id> [command]
SSH into a box, or run a command non-interactively. Manages the key at ~/.ssh/ascii_box_ed25519 automatically.
box ssh bx_f7k2q9hd
box ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -lc "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -s < ./setup.sh
box scp
Copy files to/from a box. Use bx_<id>:/path as the remote address.
# Download a file
box scp bx_f7k2q9hd:/home/user/output.zip ./output.zip
# Upload a file
box scp ./local-file.txt bx_f7k2q9hd:/home/user/
# Copy a directory recursively
box scp --recursive ./my-project bx_f7k2q9hd:/home/user/
| Flag | Description |
|---|
--recursive | Copy directories recursively |
box forward <id>
Forward one TCP port from a box to your local machine.
box forward bx_f7k2q9hd --remote 8080
box forward bx_f7k2q9hd --remote 3000 --bind 0.0.0.0
| Flag | Default | Description |
|---|
--remote <port> | required | Remote port on the box |
--local <port> | same as remote | Local port to bind |
--bind <addr> | 127.0.0.1 | Local bind address |
box desktop <id>
Open the box’s desktop streaming URL in your browser.
box desktop bx_f7k2q9hd
box desktop bx_f7k2q9hd --vnc
box desktop bx_f7k2q9hd --vnc --public
--vnc for
a VNC stream that tunnels over plain HTTPS and is far more tolerant of poor
connections. The viewer also offers a one-click switch to VNC if the default
stream struggles.
| Flag | Default | Description |
|---|
--vnc | off | Stream over VNC instead of Moonlight. More stable on poor networks. |
--public | off | With --vnc, return a URL that does not require an access token. |
The first --vnc on a box takes a few seconds while it prepares the VNC
stack (the CLI shows a spinner); subsequent opens are instant.
Snapshots
box snapshots [id]
List snapshots across your boxes, or for one box.
box snapshots
box snapshots bx_f7k2q9hd
box snapshot latest|tree|pull
Inspect or download a snapshot. Works while the box is stopped.
box snapshot latest bx_f7k2q9hd
box snapshot tree <snapshotId> # files and sizes
box snapshot pull <snapshotId> -o ./restore # download and reassemble
pull writes home_user/ (your /home/user) and docker/ (named volumes). See Snapshots.
AI agents
box prompt <id>
Send a natural-language prompt to an AI agent running inside the box.
box prompt bx_f7k2q9hd --provider claude "Fix the failing tests in this repo"
box prompt bx_f7k2q9hd --provider codex --model gpt-5.4-mini --reasoning-effort xhigh "Refactor auth module"
| Flag | Required | Values |
|---|
--provider | yes | claude, codex, claude-code |
--model | no | Provider-specific model name |
--reasoning-effort | no | Provider/model-specific level such as none, low, medium, high, xhigh, or max |
box prompt --help to fetch the current provider, model, and reasoning-effort list from the Box API.
Account
box limits
Display your current usage, quota, and subscription status.
box dashboard
Open your web dashboard in the browser. The CLI passes your local Box token to the dashboard. If that token is a service API key, Box operations still work, but creating, rotating, or revoking API keys requires signing in through the browser flow.
box config
Show the path to your local config file and its current contents.
Config is stored at ~/.config/ascii/box/config.json.
