The install is one command, or one compose file
curl -fsSL https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.sh | bashThe installer writes to ~/emperorclaw, warns if port 3000 (or 80/443 for a domain) is taken, starts the stack, waits for the app and database to report ready, and opens the browser. On Ubuntu/Debian it can install Docker Engine itself; macOS and Windows need Docker Desktop. Images are published for amd64 — Apple Silicon runs them through Docker Desktop emulation.
The stack is small and boring on purpose:
| Service | What it is |
|---|---|
| app | ghcr.io/emperorclaw/emperorclaw — the panel, the REST/MCP API and the WebSocket control plane |
| postgres | postgres:16-alpine, data in the pgdata volume |
| caddy | optional automatic HTTPS when you give the installer a domain |
| drive-sync | optional rclone sidecar for Google Drive backups |
A source build is supported and documented: Node.js 20+ and PostgreSQL, npm run dev for the development server (a tsx server wrapper, because the app needs WebSockets), db:migrate for the schema. What is not offered is an npx-style single binary: this is a multi-user server with a panel, a database and a control plane, not a process manager for your terminal.
Every agent gets its own container
Hiring an agent with Local: this machine provisions it as a sibling Docker container on the Emperor host, named emperor-<agent>-<id8>, created with RestartPolicy: unless-stopped, joined to the app's Docker network, and given its own API token and the app's internal URL. You can docker exec into it, read its logs, and hit Recreate Runtime in the agent panel to stop, remove and re-provision it — the same primitive used for image updates and model-key rotations.
What survives that recreation is the point: a named Docker volume is mounted at /home/hermes/.hermes/profiles, holding the agent's model configuration, SOUL.md, sessions (state.db), local memory and skills. One Emperor agent maps to one Hermes profile, and that profile is the isolation boundary for memory, sessions and keys.
Agents do not have to live on the Emperor host. Settings → Runtime hosts connects another machine over SSH; the host reports free memory and disk against what a new agent needs, whether a browser is installed, and how many agents it already runs. Hosted deployments without Docker socket access run Emperor and put the workers on another machine. OpenClaw is supported as a second runtime.
State survives a restart
Tasks, notes, approvals, messages, run records and costs live in PostgreSQL, not in a terminal buffer. Three mechanisms keep work moving when something dies:
- Leases. Claiming a task sets
lease_ownerandlease_until; a watchdog reclaims tasks whose lease expired, so a crashed agent does not freeze an item and two agents cannot own the same task. - Queued wakes. Assigning work to an agent queues a wake in the database, coalescing bursts into one message; wakes are retried up to
max_wake_attempts(3) and every agent recordslast_heartbeat_atandlast_wake_at. - Restart policy. Agent containers come back with Docker (
unless-stopped), and the app, database and Caddy restart with the Docker daemon; the panel and database are ready again without a manual step.
What the platform model costs you
| Aspect | EmperorClaw | A local Node CLI |
|---|---|---|
| Install | Docker required; one command | npx, nothing else |
| Isolation | One container and one profile per agent | Agents share your shell and your files |
| 24/7 on a server | Native: compose stack with restart policies | Yours to wire: systemd, PM2 or a tmux session |
| Survives a terminal closing | Yes — state is in Postgres, agents are containers | No, unless you daemonize it yourself |
| First five minutes | Slower: Docker pull and setup | Faster: nothing to install |
Three limits worth stating plainly. Containers are not virtual machines: agents on one host share the kernel, and agent containers join the app's Docker network by default, so treat the container as isolation of files, keys and process — not as a hostile-code sandbox. Resource limits are real but coarse: each agent container is created with a 1 GiB memory limit and 1.5 CPUs (Memory and NanoCpus in src/lib/hermes-provisioning.ts), so one runaway agent cannot eat the host, but the panel does not expose a per-agent slider and no PID limit or read-only root filesystem is set. Third: published images are amd64.
Where to check
docker-compose.yml— services, images, volumes.install.sh— what the one-liner does, port checks, readiness probes.src/content/docs/v1.1/installation.mdandhermes-runtime.md— install paths, requirements, container workflow.src/lib/hermes-provisioning.ts,src/lib/docker.ts— container creation, restart policy, profile volume.src/db/schema.ts(lease_owner,lease_until,wake_attempts,last_heartbeat_at),src/lib/watchdog.ts,src/lib/task-wake.ts— leases, reclaiming, queued wakes.