HappyClaw: an agent-first workspace where leaving the sandbox is one-way
A self-hosted, multi-user, agent-first Agent workbench.
At a glance
- What is it?
- HappyClaw wraps the pinned Claude Agent SDK into a long-running, multi-user service reachable from a browser and eight chat platforms, with each agent owning workspaces that own sessions and structured memory. Its design leans hard on asymmetry: ordinary members cannot reach the host filesystem, only an administrator can, and the switch that grants it does not reverse cleanly.
- Who is it for?
- HappyClaw suits a team that wants one set of agents and workspaces reachable from the tools people already use, and that needs an ordinary member's code execution to be contained by default. Four things to check before you adopt it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- riba2534/happyclaw846 ★ · +29
| Repository | 2026-09-10 | 2026-11-15 |
|---|---|---|
| riba2534/happyclaw | 817 | 846 |
29 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Agent, then Workspace, then Session: three levels with three owners
The whole data model is one hierarchy, and each level owns exactly one concern.
智能体(身份、提示词、Skills、MCP)
└── Workspace(项目目录、执行模式、环境变量、渠道挂载)
├── Workspace Memory(跨 Session 的事实、决策、经验、待跟进)
├── Main Session(工作区主会话)
├── Runtime Session(独立对话或渠道原生话题)
└── Scheduled Run(定时任务的普通或隔离运行)The agent holds identity, prompt, skills and MCP servers. The workspace holds the project directory, the execution mode, environment variables and channel mounts. The session holds conversation context. The project's own summary of why is that the agent manages identity and capability, the workspace manages files and the execution environment, and the session manages dialogue, which is a clean separation of the three things that usually get conflated in an agent tool. Session history and workspace memory are stored separately as a consequence, so forgetting one memory entry does not delete a conversation.
Host access is administrator-only and the migration does not reverse
There are two execution modes. Host runs directly in a specified local directory and suits an existing repository and a local toolchain. Container runs in a non-root Docker container with its own working directory and preinstalled toolchain. The rule that shapes everything is who gets which: ordinary members cannot downgrade a container workspace to host execution, and Script scheduled tasks are permitted only for administrators in host workspaces they already have rights to. Administrators can also enable a pure host mode from the settings, and when they do, every workspace and scheduled task they currently own migrates to host execution and can never choose Docker again. Turning the switch back off only restores the choice for future workspaces. It does not migrate anything back, which means one toggle in the wrong direction is a permanent change for that administrator's existing work.
A custom agent starts with no workspace, no session and no memory
Creating a custom agent does not give it anything implicit. There is no workspace, no session and no memory, and the user has to either create a workspace or migrate an existing non-home workspace into the new agent. The stated reason is that it avoids the agent silently inheriting the platform agent's context, which is the same reason the built-in agent exists as a separate thing in the first place. Workspaces are private file and execution isolation boundaries, and one must have its agent chosen at creation time. A non-home workspace can have its ownership migrated later, and when it moves, its files, sessions, channel bindings and memory move with it. The home workspace is the exception throughout: it is a system workspace that cannot be deleted and permanently belongs to the built-in agent.
The owner's name is kept out of memory search on purpose
Workspace memory is described as structured knowledge reused across sessions inside that workspace. It is explicitly not user-global memory, and not an archive of arbitrary files or dated notes. One detail is worth isolating because it shows the level of care: the owner's preferred form of address is not stored in generic memory at all. It lives behind a home-only owner profile facade that does not appear in general memory search, snapshot or modification interfaces. The first-run greeting that asks for it is also guarded. It only runs for the actual owner verified by the host, concurrent sessions take an onboarding lease so later sessions and service restarts do not repeat the routine, and clearing the stored name does not reset onboarding state. The built-in agent's own rules are likewise kept out of memory, since memory is described as forgettable.
Only a human reply with a confirmation phrase can publish an agent
The conversational agent builder works inside every workspace main session and ordinary runtime session under the built-in agent, and it lets a user discuss requirements over several turns, then save and preview a draft. Creating or updating the agent then requires the user to reply, in a subsequent human message, with a one-time confirmation phrase repeated verbatim. Two exclusions close the obvious holes. Scheduled tasks and sub-agents cannot publish on the user's behalf. The capability table applies the same discipline: system MCP servers are administrator-maintained and administrator-only until explicitly shared, user MCP servers only enter agents permitted to use them, and the tools actually exposed are pruned dynamically according to user permission, agent policy, workspace mode and channel context. Channel credentials follow a matching rule, since connecting an account or discovering chats never auto-binds or triggers a reply, and sending never borrows another bot's credentials.
Two of the eight channel clients are pinned to release candidates
The dependency list explains which library serves which channel, and two entries are not stable releases. The WhatsApp client is pinned to a release candidate at `^7.0.0-rc13`, and the DingTalk stream client sits at `2.1.6-beta.1`. The rest follow their platforms: a Lark SDK for Feishu, a WeCom bot SDK, discord.js for Discord, and grammY for Telegram. The agent SDK is different again, pinned to an exact version rather than a range, which matches the project's claim of a version-locked runtime and its stated decision not to reimplement tool calling and the run loop. Two native modules appear in the list as well, a SQLite binding and a pseudo-terminal library, so a build toolchain is needed rather than a pure JavaScript install. For a project that exposes an agent with filesystem and terminal access, a pre-release WhatsApp client is the dependency worth reviewing before deployment.
The Makefile documents why the project refuses to run on bun
One build-system decision comes with a full explanation in a comment, which tells you it was expensive to learn. The project uses only the native Node toolchain, npm, npx, tsx and node, and deliberately does not use bun. The reason is a handshake: the main service's WebSocket path uses the ws package with the node server upgrade event, and that mode does not fire under bun's HTTP server. The consequence is that every WebSocket handshake fails, HTTP and the API work normally, but the frontend's real-time streaming cards and notifications stop, while stdout-based channels such as Feishu are unaffected. A second comment explains a subtler trap, where a default port exported at the make level would mask a custom value from the environment file in every child process, including maintenance safety checks, and the fix reads the environment file from a shell subshell before choosing the default.
DOTENV_WEB_PORT := $(shell node -e "try { process.loadEnvFile(); } catch {} process.stdout.write(process.env.WEB_PORT || '')")The same file sets the container image to a namespace on Docker Hub with a moving tag rather than a pinned digest, and carries targets for syncing types and ensuring the SDK is current.
Formatting covers src/ only, and the test script is vitest in watch mode
The npm scripts describe three separately built TypeScript targets rather than one. The backend compiles with tsc, the web frontend builds from its own directory, and an agent runner inside the container directory builds with its own package manifest, all three usually driven through a concurrent runner. Two details in the script list are easy to misread. The formatter writes `src/**/*.ts` and nothing else, so the web, container, scripts and tests trees are outside its scope, while the format check script inspects changed files instead. And the test script is a bare `vitest`, which enters watch mode rather than running once, so a CI step needs the run flag passed through. Two optional suites sit alongside it, a real-model smoke test and a production audit. There is also a reset script that clears the administrator, which is worth knowing exists before you need it in an incident.
Editorial conclusion
HappyClaw suits a team that wants one set of agents and workspaces reachable from the tools people already use, and that needs an ordinary member's code execution to be contained by default. Four things to check before you adopt it. The privilege model is deliberately asymmetric, so decide who holds administrator rights before inviting anyone, since that role is the only path to host filesystem access and to Script scheduled tasks. Read the memory model carefully, because workspace memory and chat history are stored separately and one does not delete the other. Audit the dependency set, since two of the channel clients are pinned to release candidates and the agent SDK is pinned to an exact version that the build has a target to update. And plan around the container image defaulting to a moving tag rather than a pinned digest.
Frequently asked questions
What can an ordinary HappyClaw member do that an administrator cannot?
Nothing about execution scope. Ordinary members run in non-root Docker containers and cannot downgrade a container workspace to host execution. Script scheduled tasks are reserved for administrators in host workspaces they have rights to, and only administrators can maintain system MCP servers, which stay administrator-only until explicitly shared.
How does HappyClaw keep memory separate from chat history?
Workspace memory is structured cross-session knowledge scoped to one workspace, stored separately from session history. Forgetting a memory entry does not delete chat history. It is also not user-global memory and not a file archive, and the owner's preferred name of address is held behind a separate home-only owner profile that does not appear in memory search or snapshot interfaces.
Which chat platforms can HappyClaw connect to?
Eight messaging platforms plus the browser: Feishu over WebSocket, Telegram by bot token with long polling, QQ, DingTalk over stream mode, WeChat by QR scan through iLink, WeCom, Discord over Gateway, and WhatsApp by QR scan through Baileys. Web access uses a browser and WebSocket.
Does HappyClaw create a workspace automatically for a new agent?
No. A custom agent is created with no implicit workspace, session or memory. You have to create a workspace or migrate a non-home workspace to the agent explicitly, which is done so the new agent does not inherit the built-in agent's context.
How does HappyClaw stop an agent being published without your consent?
The conversational agent builder takes a draft through discussion and preview, and creating or updating the agent then requires you to reply in a later human message with a one-time confirmation phrase repeated verbatim. Scheduled tasks and sub-agents are explicitly barred from publishing on your behalf.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/riba2534-happyclaw)Star history chart for your README
[](https://hysenlabs.com/projects/riba2534-happyclaw)Was this useful?