HappyClaw: Self-Hosted Multi-User Claude Code Agent Workspace

What HappyClaw Is and What It Is Not

HappyClaw is built on the @anthropic-ai/claude-agent-sdk at version 0.3.280, the official TypeScript SDK for Claude agents. It wraps that SDK into a continuously running multi-user service, rather than a single-session script. The README is explicit that HappyClaw is not a simple chat API wrapper: agents run in the full Claude Code environment, with the ability to read and write project files, execute terminal commands, use a browser, call MCP servers, and load Claude Code skills.

The agent model has three levels: agent (identity and capability configuration), workspace (file system and execution environment), and runtime session (individual conversation context). An agent can have multiple workspaces, and each workspace can have multiple sessions. Workspace Memory persists structured facts, decisions, and experience across sessions, separate from conversation history. Deleting a memory entry does not remove chat history, and clearing a chat history does not remove workspace memory.

The built-in HappyClaw agent is the platform's own identity. It understands workspaces, sessions, channels, scheduled tasks, skills, MCP servers, and the permission model at a code level, not through a configurable system prompt that could be modified or forgotten. Custom agents (code review, research, operations) can be created alongside it.

Host Mode and Container Mode

HappyClaw distinguishes between two execution modes for workspaces. Host mode runs the agent directly in a specified local directory on the server machine, with access to whatever tools and toolchains are installed on the host. This is intended for administrators managing actual code repositories. Container mode runs the agent in a Docker container using the riba2534/happyclaw-agent image, with an isolated working directory and a pre-installed toolchain. This is the default for non-administrator users.

The Makefile documentation notes that the project uses native Node.js tooling rather than Bun. The WebSocket implementation relies on the ws package with @hono/node-server's server.on('upgrade') handshake, which does not trigger correctly under Bun's HTTP server, causing WebSocket-dependent features like streaming card replies and real-time notifications to fail silently while HTTP responses continue to work.

Administrators can enable a pure host mode in settings, which migrates all existing workspaces and scheduled tasks to host execution and prevents new workspaces from selecting container mode. Ordinary users continue to use Docker isolation regardless of this setting. The migration is one-way at the workspace level; disabling the setting restores the option to create new container workspaces but does not automatically migrate existing host workspaces back.

Installing and Starting HappyClaw

HappyClaw uses npm and Node.js, not Bun. The Makefile provides a dev target that installs dependencies and pulls the Docker image on first run:

make dev

For the frontend, the web/ directory is a separate package built independently:

npm run dev:all

This starts both the backend (npx tsx src/index.ts) and the frontend development server concurrently. The backend listens on port 3000 by default, configurable via the WEB_PORT environment variable in .env.

The production build compiles the backend, frontend, and the agent-runner container in parallel:

npm run build:all

To reset the admin account if credentials are lost:

npm run reset:admin

The DEPLOYMENT.md file in the repository covers production configuration, including reverse proxy setup, HTTPS termination, and backup procedures.

Messaging Channel Integration

HappyClaw integrates 8 messaging platforms: Feishu (Lark), Telegram, QQ, DingTalk, WeChat, WeCom (Enterprise WeChat), Discord, and WhatsApp. Each channel is set up per user as a bot account, and multiple accounts can be created for the same channel.

Feishu uses WebSocket with streaming card replies, image and file support, reaction support, group at-control, and topic mapping (where each Feishu topic maps to a separate session). Telegram uses long polling with Markdown and HTML formatting, long message splitting, and proxy configuration for restricted networks. DingTalk uses AI Card streaming replies. WeChat and WhatsApp use QR code login via web interface scan, with persistent session storage and automatic reconnect after disconnects.

A channel account connection does not automatically begin responding to messages. Binding a conversation to a workspace or session must be done explicitly. Channel messages then route to the bound session; topic groups in Feishu route each topic to its own session within the bound workspace. This explicit binding model prevents accidental replies and makes it possible for one server to host multiple users on the same channel with separate workspaces.

Skills, MCP Servers, and Scheduled Tasks

HappyClaw exposes capability management through several layers. User Skills are imported from a skill marketplace, an HTTPS Git repository, or a ZIP archive, and are isolated per user. Project context (CLAUDE.md, .claude/skills, MCP configuration in the workspace directory) applies at the workspace level. User MCP servers are configured per user and only enter agents that explicitly allow them. System MCP servers are configured by administrators and are restricted to administrators by default unless explicitly shared.

Built-in MCP tools cover message sending, scheduled task management, channel querying, skill management, and workspace memory reads and writes. The actual set of tools available in any session is trimmed dynamically based on user permissions, agent configuration, workspace execution mode, and channel context.

Scheduled tasks support cron schedules, fixed intervals, and one-time runs. Task types are agent tasks (run a conversation with an agent) and script tasks (run a shell script, administrator-only and restricted to host workspaces). Each task run is isolated in its own context; there is no context bleed between scheduled runs and regular sessions.

Limitations and When Not to Use HappyClaw

HappyClaw has no versioned releases. The package.json shows version 1.0.0, but there is no GitHub releases page and no changelog tied to specific commits. Teams that require reproducible deployments should pin to a specific commit hash when cloning.

The project is TypeScript and requires a Node.js runtime. It uses better-sqlite3 for its database, which is a file-based SQLite database. This is appropriate for single-server deployments with a moderate number of users, but it does not support horizontal scaling without additional infrastructure.

The container execution mode depends on Docker being available on the host. In environments where Docker-in-Docker is restricted or unavailable, container mode is not usable, limiting all users to host mode.

An alternative to HappyClaw for multi-user Claude Code access is running Claude Code directly on a server with per-user shell access, or using a commercial agent platform. HappyClaw's specific advantage over direct shell access is the messaging channel integration, the web UI, and the workspace memory system. Its disadvantage compared to a commercial platform is the absence of managed updates, official support, and enterprise features like SSO or audit logs beyond the built-in audit log.

Editorial conclusion

HappyClaw is worth adopting for teams that want multiple users to share a Claude Code-based agent through a single self-hosted server, especially when those users need access from Feishu, Telegram, or DingTalk without exposing API keys to each client. The host mode is valuable for administrators who already have code repositories and local tooling on the server, while the container mode provides practical isolation for untrusted users. Before committing, verify that the Docker image riba2534/happyclaw-agent is accessible from your network, check the DEPLOYMENT.md for production security settings, and note that the project has no versioned releases, so updates come as untagged commits.

Frequently asked questions

Official sources

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