Skip to content
nacre.sh
— Your bot

Web terminal

A full bash shell on your VM, reachable from the browser. JWT-gated, 15-minute tokens, no SSH keys to manage.

What it's for

Most of the time you won't need the terminal — the dashboard covers the happy path. It exists for the cases the dashboard doesn't cover yet:

  • Editing OpenClaw config files by hand.
  • Pasting an LLM key directly into /etc/openclaw/env so it never touches our database.
  • Tailing OpenClaw logs live.
  • Running docker compose commands.
  • Restoring a file from the /data volume.

How access works

ttyd runs as a container on your VM, bound to localhost. Caddy fronts it at https://user-<id>.nacre.sh/terminal, and gates every connection behind a JWT check.

Token TTL
15 minutes, reissued on demand
Scope claim
scope: 'terminal' + vm_id bound
Transport
WebSocket over TLS (wss)
Auth challenge
ttyd HTTP basic with bcrypt-hashed password, plus JWT query param
Session recording
We don&apos;t record your terminal. You do.

Opening the terminal

Dashboard → Terminal. Nacre calls POST /api/dashboard/vm/terminal-token to mint a short-lived token, then loads an iframe at your VM's subdomain with the token in the URL. If you sit idle past 15 minutes, the token expires — refresh the page and a new one is minted.

It's a real shell
You have root on your VM. You can break OpenClaw, corrupt the /data volume, or take the container offline. If that happens: backups run nightly to R2, and the dashboard has a "Restart OpenClaw" button that wipes the container (not the volume) and brings it back. See backups.

Useful commands

Everyday things you might run:

TaskCommand
See running containersdocker compose ps
Tail OpenClaw logsdocker compose logs -f openclaw
Restart OpenClawdocker compose restart openclaw
Edit env filesudo nano /etc/openclaw/env
Check diskdf -h /
Check memoryfree -h
Browse data volumels -la /var/lib/docker/volumes/openclaw_data/_data

Rotating the terminal password

The ttyd container checks an HTTP basic password in addition to the JWT — defence in depth. If you think the password may have leaked:

  1. Dashboard → Settings → Security → Rotate terminal password.
  2. The control plane generates a new 32-char password, stores the bcrypt hash in pgsodium, and pushes a rotate_secrets command to the agent.
  3. Agent updates the env, restarts ttyd, acknowledges back. Old tokens keep working only until they naturally expire (≤15 min).

What if the terminal won't connect?

  • Check dashboard overview — if the VM shows down orunresponsive, the terminal won't load either. The agent is either crashed or the VM is stopped.
  • Try a hard refresh — token caching in a stale iframe is the single most common cause.
  • If the terminal shows a ttyd login prompt but rejects your session, rotate the password (above).
  • Still stuck? Email support@nacre.sh with your VM hostname and we'll check the event log.