Documentation Index
Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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 the browser OAuth flow if no key is given.
box login
box login box_abc123...
Box lifecycle
box new
Create a new box.
| Flag | Default | Maximum |
|---|
--ttl | 3600 (1 hour) | 2592000 (30 days) |
box list
List all your boxes with their current state and ID.
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.
Requires the box to have a completed snapshot (i.e. it was stopped cleanly via box stop).
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.
Returns the new box ID asynchronously (HTTP 202). Requires the source box to have a completed snapshot.
Access
box ssh <id>
SSH into a box. Manages the key at ~/.ssh/ascii_box_ed25519 automatically.
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 or more ports from a box to your local machine.
box forward bx_f7k2q9hd --remote 8080
box forward bx_f7k2q9hd --remote 8080,5432 --local 8080,5433
box forward bx_f7k2q9hd --remote 3000 --bind 0.0.0.0
| Flag | Default | Description |
|---|
--remote <ports> | required | Comma-separated ports on the box |
--local <ports> | same as remote | Local ports to bind |
--bind <addr> | 127.0.0.1 | Local bind address |
box desktop <id>
Open the box’s desktop streaming URL in your browser.
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 o3 "Refactor auth module"
| Flag | Required | Values |
|---|
--provider | yes | claude, codex, claude-code |
--model | no | Provider-specific model name |
Account
box limits
Display your current usage, quota, and subscription status.
box dashboard
Open your web dashboard in the browser.
box config
Show the path to your local config file and its current contents.
Config is stored at ~/.config/ascii/box/config.json.
