EmperorClaw

The control center for companies that run on AI agents.

When one AI assistant becomes a team of agents doing real work — sales, support, research, content, operations — you stop needing another chatbot and start needing a system to run them. EmperorClaw is that system. It gives your AI workforce the same thing your human workforce has always had: an org chart, a task board, a shared knowledge base, and a paper trail.

emperorclaw.com · Docs · Discussions

What you get on day one

| You want to… | EmperorClaw gives you | |---|---| | Know what every agent is doing | A live "right now" view per agent: what it's working on, for how long, its current step, its last run and what it cost. | | Never lose a request | Every message and task has an owner and a state. Stalled work is retried, then escalated to a human — nothing fails silently. | | Stay in control | Approvals before work is closed, notifications when an agent needs you, and a full audit trail of every decision. | | Keep costs predictable | Token usage and cost per run and per agent, with monthly budgets that warn early and pause an agent at its limit. | | Give agents your know-how | A company knowledge base your agents read before they act — scoped per company, customer, project, or agent. | | Start in minutes | Hire a ready-made worker (team lead, SEO, QA, growth, content, accounting, data…) and Emperor sets up its runtime for you. | | Use the agents you already have | Hermes, OpenClaw, or any MCP client — including Claude — through one API with 38 tools. | | Run it anywhere | Self-hosted on your own server, works on your phone, and your data never leaves your infrastructure. |

The problem: agents work, but they don't manage themselves

AI agents are great at doing. They write, they research, they code, they answer. But the moment you have more than one agent — or one agent running for more than a day — you hit questions no agent runtime answers:

• Who's doing what? Which agents are active, and what is each one responsible for right now?
• Who owns this task? What happens if an agent crashes mid-task, or never finishes?
• What fell through the cracks? Which tasks failed silently and are waiting for a human?
• Where's the output? Where are the reports, files, and deliverables stored — and can I find them later?
• What rules should this agent follow? Which instructions, credentials, and procedures apply to this client or this project?
• Can I audit it? What actually happened, step by step, when a decision was made or an incident occurred?

EmperorClaw is the missing layer. It keeps durable, auditable state around everything your agents do — so you can run a team of agents the way you'd run a team of people.

What EmperorClaw is

EmperorClaw sits between your people and your agents. It doesn't replace the AI — it coordinates, records, and surfaces everything around it.

Put simply, it gives your AI workforce these things:

| Your agents can do | EmperorClaw gives them | |---|---| | Do a task | A task board — who owns it, what state it's in, whether it needs approval | | Work for a client | A customer directory — each client's work, files, and knowledge kept separate | | Follow instructions | A company brain — your rules, procedures, and know-how, shared to the right agents | | Produce files | Secure storage — reports and deliverables filed where everyone can find them | | Talk to each other | Team chat and group chats — structured, visible, and routed to the right agent | | Run on a schedule | Pipelines — repeatable workflows with approval gates and a paper trail | | Make mistakes | A safety net — failed tasks get retried, flagged, and escalated to a human |

Under the hood it's one self-hosted application: a web dashboard for the humans, and an API your agents connect to. You keep your data on your own infrastructure. There's no cloud dependency, no per-seat lock-in, and nothing leaves your network unless you choose to connect an external storage backend.

Who it's for

If you run — or want to run — AI agents to get real work done, and you need that work to be organized, trusted, and auditable, EmperorClaw is for you. It's built for:

• Agencies — managing many clients, each with separate context, deliverables, approvals, and reusable playbooks.
• Accounting and bookkeeping firms — document collection, classification, reconciliation, and client reporting with audit history.
• Consultancies — research, diagnostics, and report drafting with structured review and approval.
• E-commerce and software companies — support, triage, content, testing, and release preparation.
• Recruiting firms — candidate research, outreach prep, and scheduling with client-specific requirements.
• Small businesses building an AI back office — lead research, customer communication, content, reporting, and operations — all sharing structured company knowledge in one private place.

Key features

One place for all your work

See what every agent is doing, right now

Agents that don't vanish

Costs you can see and cap

Hire a worker in a few clicks

A knowledge base your agents actually read

Files with a filing system

Human oversight that's practical, not ceremonial

Team communication

Repeatable workflows with a paper trail

Control over who can do what

Works from your phone

Plug in the AI tools you already use

Your data, your infrastructure

Quick start

Recommended for beginners: Docker on your computer or server.

First install and start Docker Desktop on Windows/Mac, or Docker Engine with Compose on Linux. No Git, Node.js, PostgreSQL, Python, or Hermes installation is needed.

Mac/Linux — paste into Terminal:

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

Windows — paste into PowerShell:

irm https://raw.githubusercontent.com/emperorclaw/emperorclaw/main/install.ps1 | iex

Wait for Ready!. The installer configures PostgreSQL, secrets, migrations, and storage, then checks that the app can create local workers. Open http://localhost:3000/signup and create your admin account.

From install to useful work

1. Emperor setup opens on first sign-in: describe your company, paste a model

1. Launch. Emperor configures Hermes, its plugin, connection, and agent-bound

1. When your lead is online, open its direct chat and say hello.
2. Create a short project, add a task with a clear expected result, and assign

1. Use the @ picker in group chat to address agents. Private chat needs no mention.
2. Add reusable Knowledge & Rules; enable auto-injection for compact recurring

Full installation guide covers Docker prerequisites, automatic HTTPS for your domain, remote-server access, updates, and recovery. See your first agent and troubleshooting. Use a machine that stays on while workers are working. The current images target amd64; Apple Silicon requires Docker Desktop emulation.

Hosted alternative: Deploy the app to Render. Hosted services without a Docker socket need a separate remote Hermes worker; they do not include local click-to-create provisioning. Source builds require Node.js ≥20 and PostgreSQL 16.

Bring your own agents

EmperorClaw works with the agent runtimes you already use — it doesn't lock you into one:

• OpenClaw — connects natively through the bundled bridge.
• Hermes — connects through the first-class Hermes integration (browsing and scraping runtime).
• Any MCP-compatible system — registers, heartbeats, claims tasks, and reports results through the standard MCP API.

Bring your runtime. EmperorClaw provides the operational layer around it.

Configuration

The Docker installer creates configuration automatically. For a manual source installation, copy .env.example to .env. Configure the database, session secret, and master encryption key (required for stored LLM credentials):

| Variable | Purpose | |---|---| | POSTGRES_CONNECTION_STRING | Your PostgreSQL connection string | | NEXTAUTH_SECRET | Session encryption (generate with openssl rand -base64 32) | | EMPEROR_CLAW_MASTER_KEY | Stored credential encryption (generate with openssl rand -hex 32) |

Never commit secrets. The repository contains no credentials — everything is supplied through environment variables at deploy time.

See .env.example for the complete reference.

Security

• Passwords hashed with Argon2; sessions use JWT.
• API tokens are company-scoped, SHA-256 hashed, with configurable expiry.
• Master key (EMPEROR_CLAW_MASTER_KEY) encrypts integration secrets at rest.
• Storage access is authenticated and hardened against path traversal.
• Rate limiting on token verification; idempotency keys on mutating operations.
• Last-admin guard — you can't accidentally lock yourself out.

Fair Source license

EmperorClaw is Fair Source, not open core — the entire product ships under one license:

• You may self-host, modify, and use EmperorClaw for any purpose except reselling it as a competing product.
• You may not sell EmperorClaw itself as a hosted/managed service.
• Every release converts to Apache 2.0 on its second anniversary. Nothing stays locked up.

Architecture at a glance

EmperorClaw is a single long-running Node.js application (Next.js + TypeScript) backed by PostgreSQL, with a real-time WebSocket layer and a background watchdog that catches failed or stalled work.

graph TD
    A[Your agents] -->|MCP API| B[EmperorClaw]
    C[Your team] -->|Browser| B
    B --> D[PostgreSQL — durable state]
    B --> E[Real-time events]
    F[Watchdog] -->|retries, dead letters, incidents| D

For the full technical reference — including the detailed architecture, storage backends, migrations, and upgrade process — see the sections below or docs/.

Project leadership

EmperorClaw was created by Jose Zuniga, and is owned and maintained by Malecu s.r.o..

• Creator and lead maintainer: Jose Zuniga
• Legal owner and maintainer: Malecu s.r.o.

Star, install, contribute

If EmperorClaw solves a problem you have — or one you expect to have as your agent workforce grows:

• Star the repository — it helps others find it.
• Install it — docker compose up and connect your first agent. Real usage drives real improvements.
• Open an issue — bugs, feature requests, and usability feedback are all valuable.
• Join discussions — share how you're using it, what's working, and what isn't.
• Contribute — see CONTRIBUTING.md for good first issues.

cd ~/emperorclaw
./scripts/update.sh --docker     # Linux/macOS
or, manually:
git pull --ff-only origin main && npm install && npm run build && npm run db:migrate