`
WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat
│
▼
┌───────────────────────────────┐
│ Gateway │
│ (control plane) │
│ ws://127.0.0.1:18789 │
└──────────────┬────────────────┘
│
├─ Pi agent (RPC)
├─ CLI (moltbot …)
├─ WebChat UI
├─ macOS app
└─ iOS / Android nodes
`

Key subsystems

- Gateway WebSocket network — single WS control plane for clients, tools, and events (plus ops: Gateway runbook).
- Tailscale exposure — Serve/Funnel for the Gateway dashboard + WS (remote access: Remote).
- Browser control — moltbot‑managed Chrome/Chromium with CDP control.
- Canvas + A2UI — agent‑driven visual workspace (A2UI host: Canvas/A2UI).
- Voice Wake + Talk Mode — always‑on speech and continuous conversation.
- Nodes — Canvas, camera snap/clip, screen record, location.get, notifications, plus macOS‑only system.run/system.notify.

Tailscale access (Gateway dashboard)

Moltbot can auto-configure Tailscale Serve (tailnet-only) or Funnel (public) while the Gateway stays bound to loopback. Configure gateway.tailscale.mode:

- off: no Tailscale automation (default).
- serve: tailnet-only HTTPS via tailscale serve (uses Tailscale identity headers by default).
- funnel: public HTTPS via tailscale funnel (requires shared password auth).

Notes:
- gateway.bind must stay loopback when Serve/Funnel is enabled (Moltbot enforces this).
- Serve can be forced to require a password by setting gateway.auth.mode: "password" or gateway.auth.allowTailscale: false.
- Funnel refuses to start unless gateway.auth.mode: "password" is set.
- Optional: gateway.tailscale.resetOnExit to undo Serve/Funnel on shutdown.

Details: Tailscale guide · Web surfaces

Remote Gateway (Linux is great)

It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over Tailscale Serve/Funnel or SSH tunnels, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.

- Gateway host runs the exec tool and channel connections by default.
- Device nodes run device‑local actions (system.run, camera, screen recording, notifications) via node.invoke.
In short: exec runs where the Gateway lives; device actions run where the device lives.

Details: Remote access · Nodes · Security

macOS permissions via the Gateway protocol

The macOS app can run in node mode and advertises its capabilities + permission map over the Gateway WebSocket (node.list / node.describe). Clients can then execute local actions via node.invoke:

- system.run runs a local command and returns stdout/stderr/exit code; set needsScreenRecording: true to require screen-recording permission (otherwise you’ll get PERMISSION_MISSING).
- system.notify posts a user notification and fails if notifications are denied.
- canvas., camera., screen.record, and location.get are also routed via node.invoke and follow TCC permission status.

Elevated bash (host permissions) is separate from macOS TCC:

- Use /elevated on|off to toggle per‑session elevated access when enabled + allowlisted.
- Gateway persists the per‑session toggle via sessions.patch (WS method) alongside thinkingLevel, verboseLevel, model, sendPolicy, and groupActivation.

Details: Nodes · macOS app · Gateway protocol

Agent to Agent (sessions_* tools)

- Use these to coordinate work across sessions without jumping between chat surfaces.
- sessions_list — discover active sessions (agents) and their metadata.
- sessions_history — fetch transcript logs for a session.
- sessions_send — message another session; optional reply‑back ping‑pong + announce step (REPLY_SKIP, ANNOUNCE_SKIP).

Details: Session tools

Skills registry (ClawdHub)

ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed.

ClawdHub

Chat commands

Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):

- /status — compact session status (model + tokens, cost when available)
- /new or /reset — reset the session
- /compact — compact session context (summary)
- /think — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
- /verbose on|off
- /usage off|tokens|full — per-response usage footer
- /restart — restart the gateway (owner-only in groups)
- /activation mention|always — group activation toggle (groups only)

Apps (optional)

The Gateway alone delivers a great experience. All apps are optional and add extra features.

If you plan to build/run companion apps, follow the platform runbooks below.

$3

- Menu bar control for the Gateway and health.
- Voice Wake + push-to-talk overlay.
- WebChat + debug tools.
- Remote gateway control over SSH.

Note: signed builds required for macOS permissions to stick across rebuilds (see docs/mac/permissions.md).

$3

- Pairs as a node via the Bridge.
- Voice trigger forwarding + Canvas surface.
- Controlled via moltbot nodes ….

Runbook: iOS connect.

$3

- Pairs via the same Bridge + pairing flow as iOS.
- Exposes Canvas, Camera, and Screen capture commands.
- Runbook: Android connect.

Agent workspace + skills

- Workspace root: ~/clawd (configurable via agents.defaults.workspace).
- Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md.
- Skills: ~/clawd/skills//SKILL.md.

Configuration

Minimal ~/.clawdbot/moltbot.json (model + defaults):

`json5
{
agent: {
model: "anthropic/claude-opus-4-5"
}
}
`

Full configuration reference (all keys + examples).

Security model (important)

- Default: tools run on the host for the main session, so the agent has full access when it’s just you.
- Group/channel safety: set agents.defaults.sandbox.mode: "non-main" to run non‑main sessions (groups/channels) inside per‑session Docker sandboxes; bash then runs in Docker for those sessions.
- Sandbox defaults: allowlist bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn; denylist browser, canvas, nodes, cron, discord, gateway.

Details: Security guide · Docker + sandboxing · Sandbox config

$3

- Link the device: pnpm moltbot channels login (stores creds in ~/.clawdbot/credentials).
- Allowlist who can talk to the assistant via channels.whatsapp.allowFrom.
- If channels.whatsapp.groups is set, it becomes a group allowlist; include "*" to allow all.

$3

- Set TELEGRAM_BOT_TOKEN or channels.telegram.botToken (env wins).
- Optional: set channels.telegram.groups (with channels.telegram.groups."".requireMention); when set, it is a group allowlist (include "" to allow all). Also channels.telegram.allowFrom or channels.telegram.webhookUrl as needed.

`json5
{
channels: {
telegram: {
botToken: "123456:ABCDEF"
}
}
}
`

$3

- Set SLACK_BOT_TOKEN + SLACK_APP_TOKEN (or channels.slack.botToken + channels.slack.appToken).

$3

- Set DISCORD_BOT_TOKEN or channels.discord.token (env wins).
- Optional: set commands.native, commands.text, or commands.useAccessGroups, plus channels.discord.dm.allowFrom, channels.discord.guilds, or channels.discord.mediaMaxMb as needed.

`json5
{
channels: {
discord: {
token: "1234abcd"
}
}
}
`

$3

- Requires signal-cli and a channels.signal config section.

$3

- macOS only; Messages must be signed in.
- If channels.imessage.groups is set, it becomes a group allowlist; include "*" to allow all.

$3

- Configure a Teams app + Bot Framework, then add a msteams config section.
- Allowlist who can talk via msteams.allowFrom; group access via msteams.groupAllowFrom or msteams.groupPolicy: "open".

$3

- Uses the Gateway WebSocket; no separate WebChat port/config.

Browser control (optional):

`json5
{
browser: {
enabled: true,
color: "#FF4500"
}
}
``

Docs

Use these when you’re past the onboarding flow and want the deeper reference.
- Start with the docs index for navigation and “what’s where.”
- Read the architecture overview for the gateway + protocol model.
- Use the full configuration reference when you need every key and example.
- Run the Gateway by the book with the operational runbook.
- Learn how the Control UI/Web surfaces work and how to expose them safely.
- Understand remote access over SSH tunnels or tailnets.
- Follow the onboarding wizard flow for a guided setup.
- Wire external triggers via the webhook surface.
- Set up Gmail Pub/Sub triggers.
- Learn the macOS menu bar companion details.
- Platform guides: Windows (WSL2), Linux, macOS, iOS, Android
- Debug common failures with the troubleshooting guide.
- Review security guidance before exposing anything.

Advanced docs (discovery + control)

- Discovery + transports
- Bonjour/mDNS
- Gateway pairing
- Remote gateway README
- Control UI
- Dashboard

Operations & troubleshooting

- Health checks
- Gateway lock
- Background process
- Browser troubleshooting (Linux)
- Logging

Deep dives

- Agent loop
- Presence
- TypeBox schemas
- RPC adapters
- Queue

Workspace & skills

- Skills config
- Default AGENTS
- Templates: AGENTS
- Templates: BOOTSTRAP
- Templates: IDENTITY
- Templates: SOUL
- Templates: TOOLS
- Templates: USER

Platform internals

- macOS dev setup
- macOS menu bar
- macOS voice wake
- iOS node
- Android node
- Windows (WSL2)
- Linux app

Email hooks (Gmail)

- docs.molt.bot/gmail-pubsub

Molty

Moltbot was built for Molty, a space lobster AI assistant. 🦞
by Peter Steinberger and the community.

- clawd.me
- soul.md
- steipete.me
- @moltbot

Community

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs.
AI/vibe-coded PRs welcome! 🤖

Special thanks to Mario Zechner for his support and for
pi-mono.

Thanks to all clawtributors:

Show more