SoloMesh

One control plane for your AI team.

SoloMesh is a self-hosted multi-user AI Agent workspace that unifies Claude Code, Codex, and Gemini CLI with shared governance, collaboration, and automation.

English | 简体中文

---

TL;DR

• You keep the power of native runtimes, but add team-level control.
• You get Web + Feishu + Telegram entrypoints in one place.
• You can tune runtime per workspace, and runtime/model/reasoning per message.
• You can run repeatable workflows and scheduled automation without glue scripts.
• You keep data in your own environment.

Why Teams Pick SoloMesh

• One workspace for multiple runtimes: claude, codex, gemini
• Real multi-user collaboration: roles, permissions, personal workspaces, shared workspaces
• Built-in channels: Web, Feishu, Telegram
• Built-in operations: workflow templates, scheduler, logs, runtime config, MCP/Skills
• Safe-by-default controls: encrypted secrets, mount allowlist, host-mode permission checks

If you want your team to use AI runtimes like a real internal tool (not just scattered CLI sessions), SoloMesh is built for that.

Who It's For

• Engineering teams that want shared AI workflows instead of personal-only local sessions
• AI platform / DevOps teams that need runtime governance, permission boundaries, and auditability
• Product teams that need one place to run Claude/Codex/Gemini without switching tools

Typical Scenarios

1. Team Daily Operations Use scheduled prompts to generate standups, release notes, or issue digests.

2. Multi-Stage Delivery Workflow Run analysis -> implementation -> review templates with dependency checks. Example: Claude for architecture, Codex for coding/testing, Gemini for final wrap-up.

3. IM-to-Workspace Routing Route Feishu/Telegram conversations to specific workspaces with per-user controls.

4. Runtime Governance Set default runtime, expose source of secrets, and prevent risky host access by role.

Why Not Just Run CLI Directly?

Topic	Raw CLI Sessions	SoloMesh
Team Collaboration	Mostly personal sessions	Shared workspaces + permissions
Runtime Switching	Manual and fragmented	Unified runtime abstraction
Channels	Usually local terminal only	Web + Feishu + Telegram
Automation	External scripts needed	Built-in scheduler + templates
Governance	Ad hoc	RBAC + encrypted secrets + mount allowlist

What You Can Do Today

1. Chat in a clean web UI and switch runtime per message.
2. Set message-level runtime controls: runtime override, model override, and reasoning effort.
3. Use runtime directives directly in chat (@claude, @codex, @gemini).
4. Create conversation sub-agents inside one workspace for parallel threads.
5. Configure runtime credentials (Claude OAuth/setup-token/third-party token, Codex/Gemini API key).
6. Use personal home workspaces and shared workspaces with member roles.
7. Bind Feishu/Telegram sessions to target workspaces with user-level binding.
8. Create scheduled tasks (cron, interval, once) in agent mode or script mode (script mode is admin-only).
9. Build workflow templates (draft -> published -> archived) with dependency precheck and optional auto-install of missing skills on publish.
10. Generate and optimize workflow templates with AI-assisted endpoints.
11. Manage Skills and MCP servers (stdio, http, sse) per user/workspace, including host sync.
12. Browse, upload, edit, preview, and download workspace files from Web.
13. Manage users, invite codes, permission templates, and auth audit logs.
14. Expose workspace access with built-in tunnel + short links.
15. Use Chinese/English UI (auto-detect system language, user override supported).

Remote Access

SoloMesh includes a built-in remote-access kernel for exposing internal workspace URLs through a tunnel.

• Tunnel providers: cloudflared and ngrok
• Short-link entry: /r/<code>
• Link modes:
  • token mode: expiring links (TTL + optional one-time token)
  • public mode: no-token links without expiry
• Login flow: if unauthenticated, user is redirected to /login and then returned to the target workspace path.
• Workspace assistant behavior: in Web chat and IM channels (Feishu/Telegram), requests like "remote access" can auto-generate and reply with the workspace short link.

Settings path: Settings -> Remote Access

Useful env vars:

• REMOTE_ACCESS_ENABLED (enabled by default in make start)
• CLOUDFLARED_BIN
• NGROK_BIN
• REMOTE_ACCESS_AUTO_INSTALL_PROVIDERS (defaults to auto-install provider binaries)

Runtime Support

Runtime	ID	Auth	Model Override	Custom Base URL	Memory File
Claude Code	claude	OAuth / setup-token / third-party token	Yes	Yes	CLAUDE.md
Codex	codex	CODEX_API_KEY / OPENAI_API_KEY	Yes	Yes (OPENAI_BASE_URL)	AGENTS.md
Gemini CLI	gemini	GEMINI_API_KEY / GOOGLE_API_KEY	Yes	Yes (GOOGLE_GEMINI_BASE_URL)	GEMINI.md

Quick Start (3 Minutes)

For a local trial or internal team pilot:

1) Clone and start

git clone https://github.com/kexuejin/solomesh.git
cd solomesh
make start

2) Open app

Open http://localhost:3000.

3) Finish setup wizard

1. Create admin account (/setup)
2. Configure runtime credentials (/setup/providers)
3. Optionally configure channels (/setup/channels)

make start auto-installs missing dependencies and builds required parts.

How It Works

1. A message enters from Web / Feishu / Telegram.
2. SoloMesh resolves workspace, runtime, and permissions.
3. Request is dispatched to host or container runner.
4. Runtime streams output and tool events.
5. Results and state are persisted, then pushed back to the channel.

Under the Hood

Runtime Control

• Runtime abstraction by agentRuntime (claude / codex / gemini)
• Runtime list and active runtime via /api/config/runtimes
• Message-level overrides: agentRuntimeOverride, modelOverride, reasoningEffort
• Runtime directives in prompt: @claude, @codex, @gemini
• Claude OAuth endpoints:
  • /api/config/runtime/oauth/start
  • /api/config/runtime/oauth/callback
• Key source visibility (runtime / env / none) and degraded-key detection

Collaboration Channels

• System-level config: /api/config/feishu, /api/config/telegram
• User-level config and binding: /api/config/user-im/*
• Session binding + merged message query support

Workspace Collaboration and Governance

• Workspace execution modes: container / host
• Host mode guardrails: role checks + mount allowlist
• Workspace member management: owner/member roles
• Workspace bootstrapping from local path or Git URL
• User and governance controls: user management, invite codes, permission templates, audit log

Automation and Workflow

• Task schedules: cron, interval, once
• Task execution types: agent, script (admin-only for script create/update)
• Template-based automation creation
• Workflow template lifecycle: draft -> published -> archived
• Dependency precheck (provider, skill, channel, mcp)
• AI-assisted workflow endpoints:
  • /api/workflows/templates/generate
  • /api/workflows/templates/idea-optimize
  • /api/workflows/templates/:scope/:templateId/optimize
• Stage-level runtime strategy: assign different runtimes per stage (for example: Claude -> Codex -> Gemini)

Skills, MCP, and Memory

• Provider-aware skills behavior
• Per-user MCP servers (stdio, http, sse)
• Skills/MCP host sync support
• Runtime memory profile mapping:
  • claude -> CLAUDE.md
  • codex -> AGENTS.md
  • gemini -> GEMINI.md

UI Localization

• Supported UI languages: zh-CN, en
• Default: system/browser language
• User-level language switch in profile

Architecture at a Glance

flowchart TB
  U[Web / Feishu / Telegram] --> API[Hono API + WebSocket]
  API --> CTRL[Auth + RBAC + Config + Workflow + Scheduler]
  CTRL --> RUN[Host Runner / Container Runner]
  RUN --> RT[Claude / Codex / Gemini]
  RT --> MCP[MCP Bridge]
  API --> DB[(SQLite + Files + Sessions)]

Loading

Data Layout

data/
  config/          # runtime/channel config, encrypted secrets, OAuth artifacts
  db/              # sqlite
  groups/          # workspaces
  sessions/        # runtime sessions (.claude/.codex/.gemini)
  memory/          # scoped memory files
  skills/          # per-user skills
  mcp-servers/     # per-user MCP config
  ipc/             # host <-> runner IPC

Development

make install         # install dependencies + build agent-runner
make dev             # backend + frontend
make dev-backend     # backend only
make dev-web         # frontend only
make build           # build all
make typecheck       # type check all
make reset-init      # reset runtime data (destructive)

Key APIs

• Auth: /api/auth/*
• Health and monitor: /api/health, /api/status, /api/docker/build
• Workspaces: /api/groups/*, /api/groups/:jid/members*
• Workspace files: /api/groups/:jid/files*
• Workspace conversation agents: /api/groups/:jid/agents*
• Memory: /api/memory/sources, /api/memory/search, /api/memory/file, /api/memory/global
• Runtime config: /api/config/runtime*, /api/config/runtimes
• Channels: /api/config/feishu, /api/config/telegram, /api/config/user-im/*
• Remote access:
  • /api/remote-access/status
  • /api/remote-access/tunnel/start, /api/remote-access/tunnel/stop
  • /api/remote-access/links
  • /api/remote-access/preferences
  • /api/remote-access/public/entry
• Workflows: /api/workflows/templates/*
• Tasks: /api/tasks/*
• Skills: /api/skills/*
• MCP servers: /api/mcp-servers/*
• Admin and governance: /api/admin/users, /api/admin/invites, /api/admin/audit-log

Repository Layout

src/                     # backend (routing, orchestration, integrations)
web/                     # frontend (React + Vite + PWA)
container/agent-runner/  # runtime runner
container/skills/        # project-level skills
docs/architecture/       # architecture notes and ADRs

Contributing

Issues and PRs are welcome.

License

MIT