Skip to main content
The control plane is your remote interface to boxd. You interact with it by SSHing to boxd.sh.

​
Single commands

Pass any command directly: 
ssh boxd.sh new --name=myapp
ssh boxd.sh list
ssh boxd.sh exec myapp -- uname -a
ssh boxd.sh destroy myapp
This is the best mode for automation and coding agents.

​
Interactive shell

SSH without a command to get the boxd> prompt: 
ssh boxd.sh

  boxd -- your cloud, your rules

  Type 'help' for available commands.

boxd> list
name    status   ip          image
myapp   running  5.135.42.17 default

boxd> exec myapp -- hostname
myapp

boxd> exit
goodbye

​
Running commands inside machines

Use exec to run commands inside a machine: 
ssh boxd.sh exec myapp -- ls /home
ssh boxd.sh exec myapp -- sudo apt install -y nodejs
ssh boxd.sh exec myapp -- "cd /app && python3 server.py"
Commands run as the boxd user, which has passwordless sudo. The working directory is /home/boxd. For interactive commands (editors, REPLs), add --tty: 
ssh boxd.sh exec myapp --tty -- bash

​
Connecting interactively

connect opens a full interactive shell session inside a machine: 
ssh boxd.sh connect myapp
This drops you into a login shell as the boxd user. Use this for interactive work — editing files, running a REPL, debugging.
connect requires a terminal with PTY support. For automation, use exec instead.

​
Managing proxies

Every machine gets a default proxy at name.boxd.sh forwarding to port 8000. You can change the port and create additional subdomain proxies. 
# List proxies for a machine
ssh boxd.sh proxy list --vm=myapp

# Change the default proxy port
ssh boxd.sh proxy set-port --vm=myapp --port=3000

# Auto-detect listening port for the default proxy
ssh boxd.sh proxy set-port --vm=myapp --port=auto

# Create a subdomain proxy: api.myapp.boxd.sh -> port 3001
ssh boxd.sh proxy new api --vm=myapp --port=3001

# Change a named proxy's port
ssh boxd.sh proxy set-port api --vm=myapp --port=3002

# Remove a proxy
ssh boxd.sh proxy delete api --vm=myapp
The --vm flag is required for proxy new, proxy delete, and proxy set-port via SSH. For proxy list, --vm is optional — omit it to list all proxies. Inside a VM, the boxd CLI defaults to the current machine for all proxy commands.

​
JSON output

Add --json to any command for structured output: 
ssh boxd.sh list --json

[
  {
    "name": "myapp",
    "vm_id": "9645b1e8-193d-4d11-86b1-f91deff5bbfb",
    "status": "running",
    "ip": "5.135.42.17",
    "image": "default"
  }
]

​
Identity

Check your account details: 
ssh boxd.sh whoami

  user: a1b2c3d4-...
worker: worker-01
  keys: SHA256:...