EMPERORCLAWGITHUB
Home/Docs/Getting started
GUIDE 01

GETTING
STARTED.

Deploy EmperorClaw on infrastructure you control and reach a healthy first workspace without hiding the important security choices.

10 MIN READUPDATED JUL 31, 2026BEGINNER

What you need

EmperorClaw is designed for a long-running server: a VPS, VM, home server, or dedicated machine. The recommended path uses Docker and Docker Compose. A production deployment should also have a domain name, TLS termination, and working backups.

  • Docker Engine and the Compose plugin
  • At least 2 CPU cores and 4 GB RAM for a small installation
  • Persistent disk for PostgreSQL and artifact storage
  • A domain and HTTPS reverse proxy for remote access
KEEP IT PRIVATE

Do not expose PostgreSQL or internal service ports publicly. Only the HTTPS application endpoint should face the internet.

Let your coding agent install it

Open a terminal-capable coding agent on the machine where EmperorClaw should run—Codex, Claude Code, or an equivalent—and paste the brief below. It tells the agent to inspect first, preserve existing installations, use the canonical repository, and prove the deployment is healthy.

READY-TO-PASTE PROMPTSAFE EMPERORCLAW INSTALL
You are my terminal-capable infrastructure assistant. Install EmperorClaw on this machine from the canonical repository:
https://github.com/emperorclaw/emperorclaw

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

1. Inspect the operating system, CPU architecture, available memory and disk, Docker Engine, Docker Compose, Git, occupied ports, firewall state, and any existing EmperorClaw directory, containers, volumes, or database. Do not change anything yet.
2. If an EmperorClaw installation or related data already exists, stop the new-install path. Explain what you found and propose the documented backup and upgrade procedure. Never overwrite or delete an existing database, storage volume, environment file, or secrets.
3. Tell me the planned install location, local URL, and any missing prerequisites. Ask for confirmation before installing packages, changing firewall/DNS/reverse-proxy settings, exposing a port publicly, or using sudo.
4. Use only the official repository and its current documented installer. Download and inspect the installer before executing it. Do not invent Docker services, environment variables, or migration commands.
5. Generate strong secrets locally. Store them only in the protected environment file, never print their values in chat, never commit them, and never send them to an external service.
6. Keep PostgreSQL and internal services private. For a remote deployment, ask me for the intended domain before configuring HTTPS. Do not weaken authentication or TLS to make setup easier.
7. Start EmperorClaw using the documented Docker Compose flow. Preserve persistent volumes and let the application run its registered migrations.
8. Verify the result with Docker Compose status, the application health endpoint, recent application logs, and an HTTP request to the final local or HTTPS URL. Confirm there are no restart loops or failed migrations.
9. Finish with a concise report: installation path, URL, container health, backup location if applicable, what I must do in the browser, and exact safe update commands. Mention any step you could not verify.

Do not claim success until the health checks pass. If this machine is unsuitable, stop and explain the smallest safe fix.

TERMINAL ACCESS REQUIRED

A normal web chat cannot install software on your server. Use a coding agent that is running on—or securely connected to—the target machine, and review privileged actions before approving them.

Install the release manually

The installer clones the canonical repository, generates secrets, creates the environment file, and starts the stack:

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

For a manual installation, clone the repository and prepare the environment:

git clone https://github.com/emperorclaw/emperorclaw.git
cd emperorclaw
cp .env.example .env

Configure the required secrets

Open .env and set at least NEXTAUTH_SECRET and EMPEROR_CLAW_MASTER_KEY. The first signs application sessions; the second encrypts integration secrets stored by EmperorClaw.

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -hex 32      # EMPEROR_CLAW_MASTER_KEY

Set NEXTAUTH_URL to the final HTTPS address when the instance will be accessed through a domain. Review email settings before inviting other people.

Launch and verify

docker compose up -d
docker compose ps
docker compose logs --tail=100 app

The application is available at http://localhost:3000 by default. A healthy deployment shows the application and database containers running without restart loops.

Create the first workspace

Open the application, create the initial owner account, and finish workspace setup. Add a customer and project before connecting agents; that gives future work a clear scope. Then create a scoped MCP token under Settings for each runtime you connect.

  1. Create the owner account and company.
  2. Review instance and company settings.
  3. Create one customer, one project, and a small task.
  4. Upload a test file to Storage and download it again.
  5. Connect an agent only after the human workflow is understandable.

Production checklist

  • Terminate TLS with Caddy, Traefik, or nginx.
  • Back up the PostgreSQL volume and artifact storage volume together.
  • Keep the generated secrets outside source control.
  • Restrict signup and use invitations for team members.
  • Pin releases in production and read the release notes before upgrading.
  • Verify restore procedures—not only backup creation.
BackDocumentation homeNext guideStorage & Google Drive →