EmperorClaw is a control plane for running a team of AI agents, not another agent runtime

The gap it claims to fill

EmperorClaw's pitch is that it is the control center for companies that run on AI agents, and the argument is made by separating what agents do from what running them requires.

AI agents are great at doing, the README says. 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.

The questions are listed, and they read like an operations review of a team of people. Who is doing what, which agents are active and what each is responsible for right now. Who owns this task, and 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 is the output, where are the reports and files 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. And can I audit it, what actually happened step by step when a decision was made or an incident occurred.

The stated consequence of not having this layer is that agents end up working in chat threads and spreadsheets and shared folders, with fragmented state scattered across tools that were never meant to hold it together. You cannot trust it, you cannot hand it to a client, and you cannot scale it.

That framing is aimed at a specific buyer, and it is worth noticing that the phrase you cannot hand it to a client appears in the problem statement rather than in the sales pitch.

What the control plane actually provides

The README lays out the mapping between what an agent does and what the system gives it, and it is the clearest specification of the product.

Doing a task gets a task board, with who owns it, what state it is in and whether it needs approval. Working for a client gets a customer directory, keeping each client's work, files and knowledge separate. Following instructions gets a company brain, your rules, procedures and know-how, shared to the right agents. Producing files gets secure storage, with reports and deliverables filed where everyone can find them. Talking to each other gets team chat and group chats, structured, visible and routed to the right agent. Running on a schedule gets pipelines, repeatable workflows with approval gates and a paper trail. And making mistakes gets a safety net, where failed tasks get retried, flagged and escalated to a human.

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

That last clause is doing real work in the sentence, and it is the boundary of the local-first claim. The default storage is local disk, and an external backend is opt in.

The scope is broader than the feature list suggests, because there is a scheduled pipeline concept, an approval gate concept and a notification concept that are all separate from the chat and the board. It is closer to a small company operating system than to a dashboard, which is why the repository root carries an org chart metaphor in the product name.

Agents that register, heartbeat and hold leases

The mechanism that makes the task board trustworthy is a liveness protocol, and it is described more concretely than most of the marketing language.

Every agent registers itself, reports its status and sends regular heartbeats. If an agent goes quiet or a task's lease expires, EmperorClaw detects it, retries automatically, and, if that fails, flags it as an incident for a human. The claim is that work does not disappear silently.

This is the part of the design that has an analogue in conventional job scheduling, and it is worth thinking about in those terms. A lease is a time-bounded claim on a task, and lease expiry is how you detect that the worker holding it died. The alternative in most agent frameworks is that the task sits in a running state forever, which is exactly the failure the README describes as tasks that failed silently and are waiting for a human.

The human oversight story is built on the same foundation. Tasks can require approval before they are marked done, failures become visible incidents, decisions and changes are all timestamped and auditable, and an agent health view shows unanswered and failed messages, reply times and stuck agents before you would notice them.

The notifications are described in the same section, and they cover the cases that matter in a team setting: an agent mentions you, needs a decision, requests approval, assigns you a task, or cannot process a message. In-app, email, or Slack and Discord.

The knowledge base is scoped rather than global, company-wide, per-customer, per-project or per-agent, and agents read the relevant knowledge before they act. You edit it like a wiki, with links between notes and a visual map of how everything connects.

Who it is for, and the deployment shape

The README lists six kinds of user, and they cluster into two groups: agencies and professional services firms on one side, and product companies on the other.

Agencies manage many clients, each with separate context, deliverables, approvals and reusable playbooks. Accounting and bookkeeping firms do document collection, classification, reconciliation and client reporting with audit history. Consultancies do research, diagnostics and report drafting with structured review and approval. Recruiting firms do candidate research, outreach prep and scheduling with client-specific requirements.

On the other side, e-commerce and software companies use it for support, triage, content, testing and release preparation, and small businesses building an AI back office use it for lead research, customer communication, content, reporting and operations.

The audit history mention for accounting firms tells you the intended weight of the audit trail. This is a product for work that has to be defensible, not a chat client with a task list bolted on.

The deployment is a self-hosted application, and the docker-compose file shows the shape. Postgres 16 on Alpine with a healthcheck and a named volume, and the app service running the pre-built image ghcr.io/emperorclaw/emperorclaw:latest with a commented alternative to build from source instead.

Two details in that compose file are deliberate. The database port is bound to loopback only, with a comment explaining that the default credentials are not secret so the database must never be reachable from outside the host. And the app binds to 127.0.0.1 by default through EMPEROR_BIND_ADDRESS, so the deployment does not expose the dashboard to the network unless you change it.

The app also mounts the Docker socket, with a group_add for DOCKER_GID so the non-root app user can use it, which is what lets the system start sibling agent containers and update itself.

Running it, and the two secrets you must set

The environment file is unusually well commented, and it starts with the instruction that only two values must be set and that the installer generates both.

NEXTAUTH_SECRET is generated with openssl rand -base64 32 and EMPEROR_CLAW_MASTER_KEY with openssl rand -hex 32. The app refuses to start without the session encryption secret.

The install.sh and install.ps1 scripts fill in everything for you, which is the recommended path.

The database safety note is the one to internalise. Use only `npm run db:migrate` in production, because drizzle-kit push is destructive and can drop columns and data. The package.json makes that a hard stop: the db:push script echoes an error saying it is DESTRUCTIVE and can DROP columns/tables and exits 1, while db:push-dev is the escape hatch for development and db:generate creates migrations.

The Docker image runs safe migrations automatically on startup, and the runner stage copies the migrations directory and the migrate script into the image, along with a set of specific files the comment explains are needed because migrate.ts imports modules that pull in path aliases.

Behind a reverse proxy there are two more settings. EMPEROR_PUBLIC_URL overrides the public URL, and TRUSTED_PROXY_IPS lists the proxy IPs so rate limiting trusts the real client IP from X-Forwarded-For. The comment on the latter is worth reading: leave it empty when the app is directly exposed, because forwarded headers are then ignored as spoofable.

The Node requirement is 20 or newer, from the engines field and the badge, and the Dockerfile uses node:20-alpine for both the build and the runner stages with a non-root user at uid 1001.

The licence, which is the thing to check before you deploy

The licence is the most consequential thing about this project for a commercial user, and it is visible in the badge rather than hidden in a file.

The badge reads FSL-1.1-Apache-2.0, and the project licence field is recorded as one GitHub cannot classify, so the LICENSE file at the repository root is the authoritative text. The FSL is the Functional Source License, which is source-available rather than open source, with a change licence that converts to a permissive one after a period for most uses. The Apache-2.0 component of the badge suggests the Apache terms apply under some condition.

I am not giving legal advice and the README does not spell out the terms, so the instruction is to read the LICENSE file and the repository's GOVERNANCE.md before you put client data through it. For an agency handling many clients' data, and for a team that expects to modify and redistribute the software, the difference between source-available and Apache-2.0 is the difference between a decision and a negotiation.

Two other governance documents are in the repository root and worth knowing about. GOVERNANCE.md covers how decisions are made. TRADEMARK.md covers the name. OPENCLAW_ALIGNMENT.md and RETHINK.md sit alongside IMPLEMENTATION_PLAN.md, UI_UX_AUDIT_PLAN.md, TESTING.md and CLA.md, and the topics list mentions hermes-agent, jose-zuma, mission-control and openclaw, which tells you the project is aligned with a broader agent ecosystem rather than standing alone.

The repository also carries a CLA.md, a CONTRIBUTING.md, a THIRD_PARTY_NOTICES.md, a Caddyfile for reverse proxying, render.yaml for one deployment target, an openspec/ directory, install scripts for macOS, Linux and PowerShell, and a scripts/ directory with a publish-skill script and a control-plane.js with bootstrap, doctor, sync, repair and session-inspect subcommands.

Where EmperorClaw is the wrong choice

Four cases argue against it.

The first is a single agent, or two. The whole system exists to answer questions that only appear at scale, who owns what, what failed, which rules apply. If you have one agent doing one job, a task list in a file and a log is less machinery, and this is a large platform to stand up.

The second is a team that wants open source. The badge says FSL-1.1-Apache-2.0, and if your procurement treats source-available as a blocker, that settles it before any technical evaluation. The code is available to audit, which is the project's stated open development claim, but available and open are not the same thing.

The third is a deployment where a Postgres database and a Docker socket are not acceptable. The compose file mounts /var/run/docker.sock so the app can start sibling agent containers and update itself, which is a significant privilege to hand a dashboard application. If you cannot justify that in your environment, the self-update and container-spawning features are the parts to look at first.

The alternative in the same direction is to build the coordination layer yourself on top of your agent runtime. The difference in approach is that EmperorClaw supplies the org chart, the task board, the lease and heartbeat protocol, the knowledge base with scoping, the storage with visibility rules, the approval gates, the notifications and the audit log as a coherent product, while building it yourself means you get exactly the parts you implement and none of the parts you do not. For an agency with several clients and a compliance story to tell, that product is worth paying for. For a solo developer with two agents, it is a platform you will spend a weekend learning instead of using.

Editorial conclusion

EmperorClaw fits a company running several agents on real client work where the manager needs to know who owns what and what happened, since the task board, leases, heartbeats and audit trail are the layer the README says agent runtimes do not provide. It does not fit a team that wants a permissive licence, because the badge reads FSL-1.1-Apache-2.0 and the licence file is the one to read before you deploy it to a client's data. Install with the install.sh or install.ps1 scripts, which generate the two required secrets, and use `npm run db:migrate` rather than `db:push`, which the project itself marks as destructive.

Frequently asked questions

Official sources

1. emperorclaw/emperorclaw on GitHub
2. Issues
3. Project website
4. README
5. Releases