HappyClaw: a self-hosted, multi-user Claude Code workbench

The problem HappyClaw solves: Claude Code that stays online for more than one person

Claude Code is a local, single-operator tool. You run it in a terminal, in a directory you own, and when you close the terminal the session is gone. HappyClaw takes that runtime and turns it into a service. The README describes it as a self-hosted AI agent system built on the Claude Agent SDK for TypeScript, wrapping the full Claude Code runtime into a long-running multi-user service so the same agents, workspaces, capabilities and scheduled tasks are reachable from a browser, Feishu, Telegram, QQ, DingTalk, WeChat, WeCom, Discord or WhatsApp.

The intended reader is not someone who wants a chat UI over an API. The README is explicit that HappyClaw is not a chat API wrapper, and the distinction matters: agents run in a real Claude Code environment where they read and write project files, execute terminal commands, use a browser, call MCP servers and load Skills. The target user is a small team or an individual operator who wants one agent fleet with per-user isolation, and who is willing to run the infrastructure that implies. If your need is a single developer typing into a terminal, HappyClaw adds a database, a container runtime and an access-control model you will never use.

Agent, Workspace, Runtime Session: the three-level model that decides where files land

The architecture is a strict hierarchy, and getting it wrong is the main source of confusion. An Agent holds identity, prompts, Skills and MCP configuration. A Workspace is the private file and execution boundary, created under exactly one agent, carrying its own directory, environment variables, Memory, sessions and channel bindings. A Runtime Session is one conversation context inside a workspace, not a separate top-level agent. Session history and Workspace Memory are stored separately, so forgetting a Memory entry does not delete chat history.

Two built-in objects are not deletable. The built-in HappyClaw agent is the platform's main agent with a code-level fixed identity that understands workspaces, sessions, the agent builder, channels, tasks, Skills and MCP, providers and the permission model. The README notes those rules are not stored in forgettable Memory. Home Workspace is the system workspace permanently owned by that agent. Custom agents created through the conversational builder start with no implicit workspace, session or memory; the user must explicitly create a workspace or migrate a non-Home one, which is the mechanism that keeps a new agent from inheriting HappyClaw's own context.

Channel Mount is the piece that connects messaging to this tree. A private chat or ordinary group can be bound explicitly to a specific session, while a topic group binds to a workspace and each topic maps to a session. The README states that connecting an account or discovering a chat does not auto-bind and does not trigger replies. That is a deliberate safety choice: an agent will not answer a stranger who happens to find the bot. It also means a first-time operator who connects Telegram and expects replies will see silence until the mount is configured, which is a common enough confusion to be worth stating in your own runbook.

Host versus Container execution, and why members cannot opt out of Docker

Execution mode is the sharpest permission boundary in the product. Host mode runs the agent directly in a specified local directory, which suits existing repositories and a machine's own toolchain. Container mode runs in a non-root Docker container with a separate working directory and a preinstalled toolchain. Administrators with authorization can use host workspaces; ordinary members default to the Docker sandbox, and the README states plainly that ordinary members cannot downgrade a container workspace to host execution. Script-type scheduled tasks are likewise restricted to administrators on authorized host workspaces.

There is a global switch, 设置 → 宿主机集成 (Settings, Host Integration), that enables an administrator-only pure-host mode. Turning it on migrates the current administrator's workspaces and scheduled tasks to Host and removes the Docker option for them going forward. Turning it off restores the ability to choose mixed mode but does not automatically migrate existing workspaces back. That asymmetry is the kind of detail that bites during rollback: disabling the switch is not a revert.

The trade-off is honest and worth naming. Host mode gives agents the real toolchain and the real repository, and it also gives them write access to whatever the administrator authorized. Container mode bounds the blast radius at the cost of a prepared image and a separate working directory. HappyClaw does not pretend there is a mode that is both. If your team cannot decide who is allowed to run host-mode agents, you are not ready to enable the switch.

Getting it running: Node 20, Docker, and the environment you must prepare

The badges and README pin the runtime requirements: Node.js 20 or newer and TypeScript 5.9. Docker is required for container-mode workspaces, which is the default for ordinary members, so a deployment without a working container runtime will leave most users unable to execute anything. The README links DEPLOYMENT.md for production deployment; that document is the one to read before exposing the service, because the repository also ships a CI workflow at .github/workflows/ci.yml and a docs directory containing API.md, RUNTIME-ARCHITECTURE.md, ACL-MATRIX.md and BUSINESS-MODEL.md.

Configuration surfaces named in the README are worth knowing before installation. Provider setup covers the official Anthropic endpoint and third-party compatible endpoints, multiple providers, polling, weighted and failover routing, health checks and session stickiness. Capability governance is split across user Skills imported from a marketplace, an HTTPS Git repository or a ZIP file, user MCP servers that only enter agents allowed to use them, system MCP servers maintained by an administrator and shared explicitly, and Claude Code Plugins loaded through versioned runtime snapshots. Project context comes from the workspace directory itself: CLAUDE.md, .claude/skills and project MCP configuration.

The README does not give a single copy-paste install command in the portion available here, and I have not run one. Treat the installation path as something to confirm against DEPLOYMENT.md and the repository scripts rather than something to reconstruct from this article. What the material does establish is the shape of the work: provision Node, provision Docker, decide whether the administrator needs host integration, import or write the agent profiles, then configure each channel account and mount it explicitly.

Capability governance is layered, and the layering is the security model

HappyClaw separates capability sources into built-in tools, user Skills, project context, user MCP, system MCP and Claude Code Plugins. The distinction that carries security weight is between user and system MCP: user MCP servers enter only the agents permitted to use them, while system MCP servers are maintained by an administrator, are available only to the administrator by default, and reach ordinary members only after explicit sharing. Built-in MCP tools cover message sending, scheduled tasks, channel queries, Skill management and memory read and write, and the README states that the tools actually exposed are dynamically trimmed according to user permissions, agent policy, workspace mode and channel context.

That dynamic trimming is the part to verify in your own deployment rather than assume. The repository provides docs/ACL-MATRIX.md, which the README links as the permission matrix, and the agent configuration page can preview the final effective capability set for a specific workspace: project CLAUDE.md, .claude/skills, project MCP, user capabilities and same-name override sources. Use that preview. A layered model where a project file can override a user capability is powerful and also means the effective permissions of an agent are not readable from the agent profile alone.

One design choice deserves a direct comment. The README states that agents always have full tool permissions. Capability governance controls which Skills, MCP servers and plugins are loaded, not which tools the agent may call once loaded. If you expected per-tool allowlists at the agent level, this is not that, and the ACL matrix is where the actual boundary is defined.

Where HappyClaw is the wrong tool

The clearest failure mode is operational, not functional. HappyClaw is a service with users, credentials for eight messaging platforms, provider routing, scheduled jobs, usage accounting, backups and a Docker dependency. The README lists all of these as features, and each one is something that can break at 2am. A solo developer who wants Claude Code with a nicer interface is paying for multi-tenancy they will never exercise.

A second boundary is the host-mode switch. Once an administrator enables pure-host mode, their workspaces and scheduled tasks run directly on the machine in authorized directories, and disabling the switch does not migrate them back. Anyone who enables it casually, or on a shared build server, has handed agents write access to that machine's directories. The README is clear that ordinary members remain in Docker, which limits but does not eliminate the concern.

A third is channel expectations. Because connecting an account or discovering a chat does not bind or trigger replies, HappyClaw will look broken to a user who has just added the bot to a group. And the first-wake onboarding flow, which asks the verified owner for a form of address through a dedicated Owner Profile and uses an onboarding lease so concurrent sessions and restarts do not repeat the performance, is a specific behavior you should test with more than one session open. If your team's mental model is "add bot, get answers", the mount and onboarding steps will read as friction. They are the product's isolation model showing through.

Compared with a plain Claude Agent SDK service you write yourself

The real alternative is not another product. It is the Claude Agent SDK for TypeScript itself, which HappyClaw builds on and which the README links directly. Using the SDK means you write the HTTP layer, the session store, the per-user file isolation, the channel adapters, the scheduler, the usage accounting and the backup path. You get exactly the permission model you implement, and you own every bug in it.

HappyClaw's difference is that it has already made those decisions and documented them: an Agent to Workspace to Runtime Session hierarchy, a host versus container split with a one-way administrator switch, explicit channel mounts, layered capability sources with same-name override rules and a preview page, and a permission matrix in docs/ACL-MATRIX.md. The trade is that you inherit its model rather than designing your own, and its model is opinionated in ways that are hard to reverse, notably the non-deletable built-in agent and Home Workspace and the fact that custom agents do not inherit a workspace.

If your requirements fit the documented model, adopting it is less work than rebuilding it. If your requirements include per-tool allowlists at the agent level, or a permission model that is fully readable from an agent profile, the SDK route gives you that and HappyClaw does not, at least not according to the material available here.

Maintenance, upgrade surface and the MIT licence

The repository is TypeScript, MIT licensed, not archived, with the last push dated 2026-09-10. No releases were retrieved, so there is no versioned release history to reason about from this material, and the README does not describe an upgrade procedure. The upgrade surface is nonetheless visible in the design: Claude Code Plugins are loaded through versioned runtime snapshots, agent profiles keep version history with restore, user Skills record their source and version, and the README mentions consistency backups and safe restore under operations and security. Those are the mechanisms that make an upgrade less frightening, and they are also the mechanisms you need to test before you rely on them.

MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is a statement about the licence text, not legal advice, and it says nothing about the terms attached to the Claude Agent SDK, the Claude Code CLI, the model providers you route to, or the eight messaging platforms whose credentials you will store. Those are separate agreements and separate risks, and the README does not address them.

The maintenance cost that the material does support is ongoing rather than one-off. Provider routing with health checks and failover, channel accounts with per-user credentials, scheduled tasks with notification retries, and usage accounting with quotas and redemption codes all require someone to watch them. The repository links an issue tracker and a CI workflow, which tells you the project runs automated checks on main. It does not tell you how quickly fixes land, and no release history was retrieved to infer a cadence.

Editorial conclusion

Adopt HappyClaw if you already run Claude Code, want it reachable from web and IM channels, and can operate Node 20 or newer plus Docker for member isolation. Do not adopt it if you only need a chat wrapper, or if you cannot give it a host you are willing to let agents write to. Before committing, read docs/ACL-MATRIX.md and docs/RUNTIME-ARCHITECTURE.md, then check DEPLOYMENT.md and confirm which execution mode your members will land in.

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. riba2534/happyclaw on GitHub