SSH is the most direct way to use boxd. No install needed — just an SSH key.
Getting started
If your key isn’t linked yet, you’ll get a URL to sign in with GitHub. Once linked, you’re in.
To skip host key prompts, add this to ~/.ssh/config:Host boxd.sh *.boxd.sh
StrictHostKeyChecking no
UserKnownHostsFile /dev/null
Managing machines
Pass commands directly to ssh boxd.sh:
ssh boxd.sh new --name=myapp # create a machine
ssh boxd.sh list # list your machines
ssh boxd.sh fork myapp --name=copy # fork with full disk copy
ssh boxd.sh reboot myapp # reboot (cold — memory lost)
ssh boxd.sh pause myapp # pause (warm — memory preserved, sub-ms resume)
ssh boxd.sh resume myapp # resume a paused machine
ssh boxd.sh destroy myapp # destroy
boxd> prompt:
boxd -- your cloud, your rules
Type 'help' for available commands.
boxd> list
name status url image
myapp running myapp.boxd.sh default
boxd> exit
goodbye
Organizations & sharing
If you belong to an organization, the org commands and the --shared flag work both as one-shot ssh boxd.sh … commands and inside the interactive boxd> prompt — same verbs, no ssh boxd.sh prefix needed in the REPL:
boxd> org switch acme # scope this session to the "acme" org
boxd> new --name=staging --shared # create a machine shared with the whole org
boxd> fork staging --shared # fork it, keeping the fork shared with the org
boxd> org share staging # share an existing machine with the org
boxd> org unshare staging # make it private to you again (org keeps paying)
--shared flag is optional on both new and fork. Without it, a machine you create or fork in an org context is private to you (the org still pays). In particular, forking a shared machine gives you a private fork by default — only you can reach the copy, and your agent logins work in it again — while --shared keeps the fork open to the whole org. See Share a VM for the full model.
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'
Wrap commands containing shell metacharacters (&&, |, >, $, etc.) in single quotes so your local shell passes them through unchanged.
boxd user with passwordless sudo. Working directory is /home/boxd.
Additional flags:
ssh boxd.sh exec myapp -e API_KEY=secret -- CMD # set env vars
ssh boxd.sh exec myapp --timeout 30 -- CMD # timeout
ssh boxd.sh exec myapp --tty -- bash # interactive TTY
cat config.json | ssh boxd.sh exec myapp -- 'cat > /home/boxd/config.json' # pipe stdin
Copying files
Downloads write to stdout, uploads read from stdin. Paths after : are relative to /home/boxd unless they start with /.
ssh boxd.sh cp myapp:output.log > output.log # download
ssh boxd.sh cp myapp:/etc/nginx/nginx.conf > nginx.conf # absolute path
cat config.json | ssh boxd.sh cp myapp:config.json # upload
Open a shell in a machine
connect opens an interactive shell inside a machine through the control plane — no port or SSH config needed:
ssh -t boxd.sh connect myapp
boxd user with passwordless sudo. This is the quickest way in when all you have is ssh boxd.sh.
Direct SSH, SCP, port-forwarding, editors
Each machine listens on a dedicated SSH port (in the 10000–30000 range) on the shared proxy IP, so plain ssh, scp, rsync, port-forwarding, and editor Remote-SSH all go through a per-VM host alias in your ~/.ssh/config rather than the bare domain. The boxd CLI writes those aliases for you (the alias is a local SSH-config shortcut, not a DNS name):
boxd ssh-config # writes `<vm>.boxd` Host entries (with the right Port) to ~/.ssh/config
ssh myapp.boxd # shell
scp ./file myapp.boxd:/home/boxd/ # copy
ssh -L 5432:localhost:5432 myapp.boxd # port-forward
# VS Code / Cursor / Zed / JetBrains: pick `myapp.boxd` from the Remote-SSH picker
boxd new, fork, list, and destroy keep the block in sync automatically. See the CLI reference for details.
The alias lives in your local ~/.ssh/config, so direct SSH (and editor Remote-SSH) needs the boxd CLI — install it with curl -fsSL https://boxd.sh/downloads/install.sh | sh, then boxd ssh-config (or any boxd new / list) writes and keeps the <vm>.boxd entries in sync. Without the CLI, ssh -t boxd.sh connect myapp (above) still gets you a shell through the control plane.
Connecting to the bare myapp.boxd.sh hostname (port 22) reaches the management REPL, not the machine — that port is the control plane. Use ssh -t boxd.sh connect myapp for a quick shell, or the myapp.boxd alias for direct SSH.
Direct SSH only works for the machine owner. Your SSH key must match the key registered to your account.
Managing proxies
Every machine gets a default proxy at name.boxd.sh forwarding to port 8000.
ssh boxd.sh proxy list --vm=myapp # list
ssh boxd.sh proxy set-port --vm=myapp --port=3000 # change port
ssh boxd.sh proxy set-port --vm=myapp --port=auto # auto-detect
ssh boxd.sh proxy new api --vm=myapp --port=3001 # subdomain
ssh boxd.sh proxy delete api --vm=myapp # remove
Exposing raw TCP/UDP ports
Proxies route HTTPS only. To expose a database, an SSH daemon, or any non-HTTP service, expose opens a raw TCP/UDP port on the machine’s public proxy, forwarded straight to a port inside the VM. The public port is allocated from the 40000–60000 range; connect on name.boxd.sh at that port. See Port forwarding.
ssh boxd.sh expose myapp 5432 # forward a public port -> :5432 in the VM (TCP)
ssh boxd.sh expose myapp 9999 --udp # UDP instead
ssh boxd.sh expose myapp 7777 --tcp --udp # both protocols on one allocated public port
ssh boxd.sh expose --list # list all your exposed ports
ssh boxd.sh expose myapp 5432 --remove # remove a forward, freeing the public port
boxd> prompt too (drop the ssh boxd.sh prefix).
JSON output
Add --json to any command for structured output:
[
{
"name": "myapp",
"vm_id": "9645b1e8-...",
"status": "running",
"url": "myapp.boxd.sh",
"image": "default"
}
]
Identity
Adding more SSH keys
SSH from a different machine with a new key and go through the same link flow. The new key gets linked to your existing account (matched by GitHub identity). 