GETTING
STARTED.

What you need

One thing: Docker. Docker Desktop on Windows or Mac, or Docker Engine with the Compose v2 plugin on Linux. You do not need Git, Node.js, PostgreSQL or Python; the database runs inside Docker.

• A machine that stays on while agents work: a VPS, a home server or your own computer
• At least 2 CPU cores and 4 GB RAM for a small installation
• Disk space for the database and stored files

Images target amd64. Apple Silicon runs them through Docker Desktop emulation.

Install

# Mac / Linux
curl -fsSL https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.ps1 | iex

The installer:

1. Checks for Docker. If it is missing, it installs it on Linux, uses Homebrew on Mac or winget on Windows when available, or opens the download page.
2. Downloads about ten files (the Compose file, Caddy config, .env.example and update and backup scripts) into ~/emperorclaw. It does not clone the repository.
3. Creates .env and generates NEXTAUTH_SECRET, EMPEROR_CLAW_MASTER_KEY and POSTGRES_PASSWORD. Existing values are never overwritten.
4. Pulls the prebuilt images, starts the app and PostgreSQL, and waits until the app is healthy.
5. Opens http://localhost:3000/signup.

Running it again is safe: your .env and data are kept.

Your own domain with automatic HTTPS

Point the domain's DNS A record at the server and allow inbound ports 80 and 443. Then pass the domain to the installer. It configures Caddy, which obtains and renews the certificate for you. You do not need your own reverse proxy.

# Mac / Linux
curl -fsSL https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.sh | bash -s -- --domain claw.example.com

# Windows (PowerShell)
irm https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.ps1 -OutFile emperor-install.ps1
.\emperor-install.ps1 -Domain claw.example.com

Then open https://claw.example.com/signup. Other options: --admin-email / -AdminEmail sets the platform admin, --dir / -InstallDir changes the install folder, and --no-browser / -NoBrowser skips opening the browser.

First run: Emperor setup

1. Create your admin account on the sign-up page.
2. Describe your company.
3. Paste a model key. OpenRouter is recommended; the key is checked before anything starts.
4. Pick a suggested team and launch. Emperor creates each agent, its access token and its connection for you.
5. When your lead agent is online, open its chat and say hello. It writes your company's Knowledge & Rules.

Then create a project, add a task with a clear expected result, assign it, and watch it move.

Update, stop and recover

From the install folder (~/emperorclaw by default):

bash scripts/update.sh --docker      # Mac / Linux
.\scripts\update.ps1 -Docker         # Windows

# or by hand
docker compose pull
docker compose up -d

Stop with docker compose down; your data is kept. Never use docker compose down -v, which deletes the data volumes. If startup fails, check docker compose logs --tail=100 app postgres.

Building from source instead of Docker needs Node.js 20 or newer and PostgreSQL 16; see the README.

Let your coding agent install it

Prefer to hand the job to a terminal-capable coding agent (Codex, Claude Code or similar) running on the target machine? Paste the brief below.

You are my terminal-capable infrastructure assistant. Install EmperorClaw on this machine using its official installer:
https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.sh (Mac/Linux)
https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.ps1 (Windows)

Work carefully and keep me informed. Follow this operating brief:

1. Inspect the operating system, CPU architecture, memory and disk, Docker and Docker Compose v2, occupied ports (3000, and 80/443 if I want a domain), and any existing ~/emperorclaw folder, containers or volumes. Do not change anything yet.
2. If an EmperorClaw installation already exists, do not reinstall over it blindly. Explain what you found and propose the documented update: bash scripts/update.sh --docker (or .\scripts\update.ps1 -Docker). Never delete a database volume, storage volume or .env file.
3. Tell me the install location, URL and any missing prerequisite. Ask before installing packages, using sudo, or changing firewall or DNS settings.
4. Download the installer, read it, then run it. If I want a public domain, ask me for it and pass --domain (or -Domain on Windows) so the installer sets up HTTPS with Caddy. Do not write your own reverse proxy or invent environment variables.
5. The installer generates the secrets in .env. Never print their values in chat, commit them or send them anywhere.
6. Verify with docker compose ps, the /api/health endpoint, recent app logs, and a request to the final URL. Confirm there are no restart loops.
7. Finish with a short report: install path, URL, container health, what I must do in the browser (sign up, then Emperor setup), and the update command. Mention anything you could not verify.

Do not claim success until the health checks pass.

Production checklist

• Use --domain so the app is only reachable over HTTPS.
• Back up the database regularly (scripts/backup-db.sh or scripts\backup-db.ps1) together with stored files, and keep .env backed up securely.
• Use invitations for team members and give each person the smallest role they need.
• Read the release notes before updating.
• Test a restore, not only the backup.