Add ez-assistant and kerberos service folders
This commit is contained in:
kelin
235
docker-compose/ez-assistant/docs/start/clawd.md
Normal file
235
docker-compose/ez-assistant/docs/start/clawd.md
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
summary: "End-to-end guide for running Moltbot as a personal assistant with safety cautions"
|
||||
read_when:
|
||||
- Onboarding a new assistant instance
|
||||
- Reviewing safety/permission implications
|
||||
---
|
||||
# Building a personal assistant with Moltbot (Clawd-style)
|
||||
|
||||
Moltbot is a WhatsApp + Telegram + Discord + iMessage gateway for **Pi** agents. Plugins add Mattermost. This guide is the "personal assistant" setup: one dedicated WhatsApp number that behaves like your always-on agent.
|
||||
|
||||
## ⚠️ Safety first
|
||||
|
||||
You’re putting an agent in a position to:
|
||||
- run commands on your machine (depending on your Pi tool setup)
|
||||
- read/write files in your workspace
|
||||
- send messages back out via WhatsApp/Telegram/Discord/Mattermost (plugin)
|
||||
|
||||
Start conservative:
|
||||
- Always set `channels.whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
|
||||
- Use a dedicated WhatsApp number for the assistant.
|
||||
- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agents.defaults.heartbeat.every: "0m"`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node **22+**
|
||||
- Moltbot available on PATH (recommended: global install)
|
||||
- A second phone number (SIM/eSIM/prepaid) for the assistant
|
||||
|
||||
```bash
|
||||
npm install -g moltbot@latest
|
||||
# or: pnpm add -g moltbot@latest
|
||||
```
|
||||
|
||||
From source (development):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/moltbot/moltbot.git
|
||||
cd moltbot
|
||||
pnpm install
|
||||
pnpm ui:build # auto-installs UI deps on first run
|
||||
pnpm build
|
||||
pnpm link --global
|
||||
```
|
||||
|
||||
## The two-phone setup (recommended)
|
||||
|
||||
You want this:
|
||||
|
||||
```
|
||||
Your Phone (personal) Second Phone (assistant)
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Your WhatsApp │ ──────▶ │ Assistant WA │
|
||||
│ +1-555-YOU │ message │ +1-555-CLAWD │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│ linked via QR
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Your Mac │
|
||||
│ (moltbot) │
|
||||
│ Pi agent │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
If you link your personal WhatsApp to Moltbot, every message to you becomes “agent input”. That’s rarely what you want.
|
||||
|
||||
## 5-minute quick start
|
||||
|
||||
1) Pair WhatsApp Web (shows QR; scan with the assistant phone):
|
||||
|
||||
```bash
|
||||
moltbot channels login
|
||||
```
|
||||
|
||||
2) Start the Gateway (leave it running):
|
||||
|
||||
```bash
|
||||
moltbot gateway --port 18789
|
||||
```
|
||||
|
||||
3) Put a minimal config in `~/.clawdbot/moltbot.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } }
|
||||
}
|
||||
```
|
||||
|
||||
Now message the assistant number from your allowlisted phone.
|
||||
|
||||
When onboarding finishes, we auto-open the dashboard with your gateway token and print the tokenized link. To reopen later: `moltbot dashboard`.
|
||||
|
||||
## Give the agent a workspace (AGENTS)
|
||||
|
||||
Clawd reads operating instructions and “memory” from its workspace directory.
|
||||
|
||||
By default, Moltbot uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
|
||||
|
||||
Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
|
||||
|
||||
```bash
|
||||
moltbot setup
|
||||
```
|
||||
|
||||
Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
Memory workflow: [Memory](/concepts/memory)
|
||||
|
||||
Optional: choose a different workspace with `agents.defaults.workspace` (supports `~`).
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/clawd"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
skipBootstrap: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## The config that turns it into “an assistant”
|
||||
|
||||
Moltbot defaults to a good assistant setup, but you’ll usually want to tune:
|
||||
- persona/instructions in `SOUL.md`
|
||||
- thinking defaults (if desired)
|
||||
- heartbeats (once you trust it)
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
logging: { level: "info" },
|
||||
agent: {
|
||||
model: "anthropic/claude-opus-4-5",
|
||||
workspace: "~/clawd",
|
||||
thinkingDefault: "high",
|
||||
timeoutSeconds: 1800,
|
||||
// Start with 0; enable later.
|
||||
heartbeat: { every: "0m" }
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true }
|
||||
}
|
||||
}
|
||||
},
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@clawd", "clawd"]
|
||||
}
|
||||
},
|
||||
session: {
|
||||
scope: "per-sender",
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
reset: {
|
||||
mode: "daily",
|
||||
atHour: 4,
|
||||
idleMinutes: 10080
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sessions and memory
|
||||
|
||||
- Session files: `~/.clawdbot/agents/<agentId>/sessions/{{SessionId}}.jsonl`
|
||||
- Session metadata (token usage, last route, etc): `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (legacy: `~/.clawdbot/sessions/sessions.json`)
|
||||
- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
|
||||
- `/compact [instructions]` compacts the session context and reports the remaining context budget.
|
||||
|
||||
## Heartbeats (proactive mode)
|
||||
|
||||
By default, Moltbot runs a heartbeat every 30 minutes with the prompt:
|
||||
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
|
||||
Set `agents.defaults.heartbeat.every: "0m"` to disable.
|
||||
|
||||
- If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# Heading`), Moltbot skips the heartbeat run to save API calls.
|
||||
- If the file is missing, the heartbeat still runs and the model decides what to do.
|
||||
- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), Moltbot suppresses outbound delivery for that heartbeat.
|
||||
- Heartbeats run full agent turns — shorter intervals burn more tokens.
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
heartbeat: { every: "30m" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Media in and out
|
||||
|
||||
Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
|
||||
- `{{MediaPath}}` (local temp file path)
|
||||
- `{{MediaUrl}}` (pseudo-URL)
|
||||
- `{{Transcript}}` (if audio transcription is enabled)
|
||||
|
||||
Outbound attachments from the agent: include `MEDIA:<path-or-url>` on its own line (no spaces). Example:
|
||||
|
||||
```
|
||||
Here’s the screenshot.
|
||||
MEDIA:/tmp/screenshot.png
|
||||
```
|
||||
|
||||
Moltbot extracts these and sends them as media alongside the text.
|
||||
|
||||
## Operations checklist
|
||||
|
||||
```bash
|
||||
moltbot status # local status (creds, sessions, queued events)
|
||||
moltbot status --all # full diagnosis (read-only, pasteable)
|
||||
moltbot status --deep # adds gateway health probes (Telegram + Discord)
|
||||
moltbot health --json # gateway health snapshot (WS)
|
||||
```
|
||||
|
||||
Logs live under `/tmp/moltbot/` (default: `moltbot-YYYY-MM-DD.log`).
|
||||
|
||||
## Next steps
|
||||
|
||||
- WebChat: [WebChat](/web/webchat)
|
||||
- Gateway ops: [Gateway runbook](/gateway)
|
||||
- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
|
||||
- macOS menu bar companion: [Moltbot macOS app](/platforms/macos)
|
||||
- iOS node app: [iOS app](/platforms/ios)
|
||||
- Android node app: [Android app](/platforms/android)
|
||||
- Windows status: [Windows (WSL2)](/platforms/windows)
|
||||
- Linux status: [Linux app](/platforms/linux)
|
||||
- Security: [Security](/gateway/security)
|
||||
204
docker-compose/ez-assistant/docs/start/getting-started.md
Normal file
204
docker-compose/ez-assistant/docs/start/getting-started.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
summary: "Beginner guide: from zero to first message (wizard, auth, channels, pairing)"
|
||||
read_when:
|
||||
- First time setup from zero
|
||||
- You want the fastest path from install → onboarding → first message
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
|
||||
|
||||
Fastest chat: open the Control UI (no channel setup needed). Run `moltbot dashboard`
|
||||
and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
|
||||
Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
|
||||
|
||||
Recommended path: use the **CLI onboarding wizard** (`moltbot onboard`). It sets up:
|
||||
- model/auth (OAuth recommended)
|
||||
- gateway settings
|
||||
- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
|
||||
- pairing defaults (secure DMs)
|
||||
- workspace bootstrap + skills
|
||||
- optional background service
|
||||
|
||||
If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
|
||||
|
||||
Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`),
|
||||
so group/channel sessions are sandboxed. If you want the main agent to always
|
||||
run on host, set an explicit per-agent override:
|
||||
|
||||
```json
|
||||
{
|
||||
"routing": {
|
||||
"agents": {
|
||||
"main": {
|
||||
"workspace": "~/clawd",
|
||||
"sandbox": { "mode": "off" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 0) Prereqs
|
||||
|
||||
- Node `>=22`
|
||||
- `pnpm` (optional; recommended if you build from source)
|
||||
- **Recommended:** Brave Search API key for web search. Easiest path:
|
||||
`moltbot configure --section web` (stores `tools.web.search.apiKey`).
|
||||
See [Web tools](/tools/web).
|
||||
|
||||
macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
|
||||
Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
|
||||
|
||||
## 1) Install the CLI (recommended)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://molt.bot/install.sh | bash
|
||||
```
|
||||
|
||||
Installer options (install method, non-interactive, from GitHub): [Install](/install).
|
||||
|
||||
Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
iwr -useb https://molt.bot/install.ps1 | iex
|
||||
```
|
||||
|
||||
Alternative (global install):
|
||||
|
||||
```bash
|
||||
npm install -g moltbot@latest
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g moltbot@latest
|
||||
```
|
||||
|
||||
## 2) Run the onboarding wizard (and install the service)
|
||||
|
||||
```bash
|
||||
moltbot onboard --install-daemon
|
||||
```
|
||||
|
||||
What you’ll choose:
|
||||
- **Local vs Remote** gateway
|
||||
- **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
|
||||
- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
|
||||
- **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
|
||||
- **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
|
||||
- **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
|
||||
|
||||
Wizard doc: [Wizard](/start/wizard)
|
||||
|
||||
### Auth: where it lives (important)
|
||||
|
||||
- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
|
||||
|
||||
- OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
|
||||
- Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
|
||||
Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
|
||||
|
||||
## 3) Start the Gateway
|
||||
|
||||
If you installed the service during onboarding, the Gateway should already be running:
|
||||
|
||||
```bash
|
||||
moltbot gateway status
|
||||
```
|
||||
|
||||
Manual run (foreground):
|
||||
|
||||
```bash
|
||||
moltbot gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
Dashboard (local loopback): `http://127.0.0.1:18789/`
|
||||
If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).
|
||||
|
||||
⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
|
||||
channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
|
||||
|
||||
## 3.5) Quick verify (2 min)
|
||||
|
||||
```bash
|
||||
moltbot status
|
||||
moltbot health
|
||||
moltbot security audit --deep
|
||||
```
|
||||
|
||||
## 4) Pair + connect your first chat surface
|
||||
|
||||
### WhatsApp (QR login)
|
||||
|
||||
```bash
|
||||
moltbot channels login
|
||||
```
|
||||
|
||||
Scan via WhatsApp → Settings → Linked Devices.
|
||||
|
||||
WhatsApp doc: [WhatsApp](/channels/whatsapp)
|
||||
|
||||
### Telegram / Discord / others
|
||||
|
||||
The wizard can write tokens/config for you. If you prefer manual config, start with:
|
||||
- Telegram: [Telegram](/channels/telegram)
|
||||
- Discord: [Discord](/channels/discord)
|
||||
- Mattermost (plugin): [Mattermost](/channels/mattermost)
|
||||
|
||||
**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.
|
||||
|
||||
## 5) DM safety (pairing approvals)
|
||||
|
||||
Default posture: unknown DMs get a short code and messages are not processed until approved.
|
||||
If your first DM gets no reply, approve the pairing:
|
||||
|
||||
```bash
|
||||
moltbot pairing list whatsapp
|
||||
moltbot pairing approve whatsapp <code>
|
||||
```
|
||||
|
||||
Pairing doc: [Pairing](/start/pairing)
|
||||
|
||||
## From source (development)
|
||||
|
||||
If you’re hacking on Moltbot itself, run from source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/moltbot/moltbot.git
|
||||
cd moltbot
|
||||
pnpm install
|
||||
pnpm ui:build # auto-installs UI deps on first run
|
||||
pnpm build
|
||||
moltbot onboard --install-daemon
|
||||
```
|
||||
|
||||
If you don’t have a global install yet, run the onboarding step via `pnpm moltbot ...` from the repo.
|
||||
`pnpm build` also bundles A2UI assets; if you need to run just that step, use `pnpm canvas:a2ui:bundle`.
|
||||
|
||||
Gateway (from this repo):
|
||||
|
||||
```bash
|
||||
node dist/entry.js gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
## 7) Verify end-to-end
|
||||
|
||||
In a new terminal, send a test message:
|
||||
|
||||
```bash
|
||||
moltbot message send --target +15555550123 --message "Hello from Moltbot"
|
||||
```
|
||||
|
||||
If `moltbot health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
|
||||
|
||||
Tip: `moltbot status --all` is the best pasteable, read-only debug report.
|
||||
Health probes: `moltbot health` (or `moltbot status --deep`) asks the running gateway for a health snapshot.
|
||||
|
||||
## Next steps (optional, but great)
|
||||
|
||||
- macOS menu bar app + voice wake: [macOS app](/platforms/macos)
|
||||
- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
|
||||
- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)
|
||||
- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)
|
||||
182
docker-compose/ez-assistant/docs/start/hubs.md
Normal file
182
docker-compose/ez-assistant/docs/start/hubs.md
Normal file
@@ -0,0 +1,182 @@
|
||||
---
|
||||
summary: "Hubs that link to every Moltbot doc"
|
||||
read_when:
|
||||
- You want a complete map of the documentation
|
||||
---
|
||||
# Docs hubs
|
||||
|
||||
Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
|
||||
|
||||
## Start here
|
||||
|
||||
- [Index](/)
|
||||
- [Getting Started](/start/getting-started)
|
||||
- [Onboarding](/start/onboarding)
|
||||
- [Wizard](/start/wizard)
|
||||
- [Setup](/start/setup)
|
||||
- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
|
||||
- [Help](/help)
|
||||
- [Configuration](/gateway/configuration)
|
||||
- [Configuration examples](/gateway/configuration-examples)
|
||||
- [Moltbot assistant (Clawd)](/start/clawd)
|
||||
- [Showcase](/start/showcase)
|
||||
- [Lore](/start/lore)
|
||||
|
||||
## Installation + updates
|
||||
|
||||
- [Docker](/install/docker)
|
||||
- [Nix](/install/nix)
|
||||
- [Updating / rollback](/install/updating)
|
||||
- [Bun workflow (experimental)](/install/bun)
|
||||
|
||||
## Core concepts
|
||||
|
||||
- [Architecture](/concepts/architecture)
|
||||
- [Network hub](/network)
|
||||
- [Agent runtime](/concepts/agent)
|
||||
- [Agent workspace](/concepts/agent-workspace)
|
||||
- [Memory](/concepts/memory)
|
||||
- [Agent loop](/concepts/agent-loop)
|
||||
- [Streaming + chunking](/concepts/streaming)
|
||||
- [Multi-agent routing](/concepts/multi-agent)
|
||||
- [Compaction](/concepts/compaction)
|
||||
- [Sessions](/concepts/session)
|
||||
- [Sessions (alias)](/concepts/sessions)
|
||||
- [Session pruning](/concepts/session-pruning)
|
||||
- [Session tools](/concepts/session-tool)
|
||||
- [Queue](/concepts/queue)
|
||||
- [Slash commands](/tools/slash-commands)
|
||||
- [RPC adapters](/reference/rpc)
|
||||
- [TypeBox schemas](/concepts/typebox)
|
||||
- [Timezone handling](/concepts/timezone)
|
||||
- [Presence](/concepts/presence)
|
||||
- [Discovery + transports](/gateway/discovery)
|
||||
- [Bonjour](/gateway/bonjour)
|
||||
- [Channel routing](/concepts/channel-routing)
|
||||
- [Groups](/concepts/groups)
|
||||
- [Group messages](/concepts/group-messages)
|
||||
- [Model failover](/concepts/model-failover)
|
||||
- [OAuth](/concepts/oauth)
|
||||
|
||||
## Providers + ingress
|
||||
|
||||
- [Chat channels hub](/channels)
|
||||
- [Model providers hub](/providers/models)
|
||||
- [WhatsApp](/channels/whatsapp)
|
||||
- [Telegram](/channels/telegram)
|
||||
- [Telegram (grammY notes)](/channels/grammy)
|
||||
- [Slack](/channels/slack)
|
||||
- [Discord](/channels/discord)
|
||||
- [Mattermost](/channels/mattermost) (plugin)
|
||||
- [Signal](/channels/signal)
|
||||
- [iMessage](/channels/imessage)
|
||||
- [Location parsing](/channels/location)
|
||||
- [WebChat](/web/webchat)
|
||||
- [Webhooks](/automation/webhook)
|
||||
- [Gmail Pub/Sub](/automation/gmail-pubsub)
|
||||
|
||||
## Gateway + operations
|
||||
|
||||
- [Gateway runbook](/gateway)
|
||||
- [Gateway pairing](/gateway/pairing)
|
||||
- [Gateway lock](/gateway/gateway-lock)
|
||||
- [Background process](/gateway/background-process)
|
||||
- [Health](/gateway/health)
|
||||
- [Heartbeat](/gateway/heartbeat)
|
||||
- [Doctor](/gateway/doctor)
|
||||
- [Logging](/gateway/logging)
|
||||
- [Sandboxing](/gateway/sandboxing)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Control UI](/web/control-ui)
|
||||
- [Remote access](/gateway/remote)
|
||||
- [Remote gateway README](/gateway/remote-gateway-readme)
|
||||
- [Tailscale](/gateway/tailscale)
|
||||
- [Security](/gateway/security)
|
||||
- [Troubleshooting](/gateway/troubleshooting)
|
||||
|
||||
## Tools + automation
|
||||
|
||||
- [Tools surface](/tools)
|
||||
- [OpenProse](/prose)
|
||||
- [CLI reference](/cli)
|
||||
- [Exec tool](/tools/exec)
|
||||
- [Elevated mode](/tools/elevated)
|
||||
- [Cron jobs](/automation/cron-jobs)
|
||||
- [Cron vs Heartbeat](/automation/cron-vs-heartbeat)
|
||||
- [Thinking + verbose](/tools/thinking)
|
||||
- [Models](/concepts/models)
|
||||
- [Sub-agents](/tools/subagents)
|
||||
- [Agent send CLI](/tools/agent-send)
|
||||
- [Terminal UI](/tui)
|
||||
- [Browser control](/tools/browser)
|
||||
- [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
|
||||
- [Polls](/automation/poll)
|
||||
|
||||
## Nodes, media, voice
|
||||
|
||||
- [Nodes overview](/nodes)
|
||||
- [Camera](/nodes/camera)
|
||||
- [Images](/nodes/images)
|
||||
- [Audio](/nodes/audio)
|
||||
- [Location command](/nodes/location-command)
|
||||
- [Voice wake](/nodes/voicewake)
|
||||
- [Talk mode](/nodes/talk)
|
||||
|
||||
## Platforms
|
||||
|
||||
- [Platforms overview](/platforms)
|
||||
- [macOS](/platforms/macos)
|
||||
- [iOS](/platforms/ios)
|
||||
- [Android](/platforms/android)
|
||||
- [Windows (WSL2)](/platforms/windows)
|
||||
- [Linux](/platforms/linux)
|
||||
- [Web surfaces](/web)
|
||||
|
||||
## macOS companion app (advanced)
|
||||
|
||||
- [macOS dev setup](/platforms/mac/dev-setup)
|
||||
- [macOS menu bar](/platforms/mac/menu-bar)
|
||||
- [macOS voice wake](/platforms/mac/voicewake)
|
||||
- [macOS voice overlay](/platforms/mac/voice-overlay)
|
||||
- [macOS WebChat](/platforms/mac/webchat)
|
||||
- [macOS Canvas](/platforms/mac/canvas)
|
||||
- [macOS child process](/platforms/mac/child-process)
|
||||
- [macOS health](/platforms/mac/health)
|
||||
- [macOS icon](/platforms/mac/icon)
|
||||
- [macOS logging](/platforms/mac/logging)
|
||||
- [macOS permissions](/platforms/mac/permissions)
|
||||
- [macOS remote](/platforms/mac/remote)
|
||||
- [macOS signing](/platforms/mac/signing)
|
||||
- [macOS release](/platforms/mac/release)
|
||||
- [macOS gateway (launchd)](/platforms/mac/bundled-gateway)
|
||||
- [macOS XPC](/platforms/mac/xpc)
|
||||
- [macOS skills](/platforms/mac/skills)
|
||||
- [macOS Peekaboo](/platforms/mac/peekaboo)
|
||||
|
||||
## Workspace + templates
|
||||
|
||||
- [Skills](/tools/skills)
|
||||
- [ClawdHub](/tools/clawdhub)
|
||||
- [Skills config](/tools/skills-config)
|
||||
- [Default AGENTS](/reference/AGENTS.default)
|
||||
- [Templates: AGENTS](/reference/templates/AGENTS)
|
||||
- [Templates: BOOTSTRAP](/reference/templates/BOOTSTRAP)
|
||||
- [Templates: HEARTBEAT](/reference/templates/HEARTBEAT)
|
||||
- [Templates: IDENTITY](/reference/templates/IDENTITY)
|
||||
- [Templates: SOUL](/reference/templates/SOUL)
|
||||
- [Templates: TOOLS](/reference/templates/TOOLS)
|
||||
- [Templates: USER](/reference/templates/USER)
|
||||
|
||||
## Experiments (exploratory)
|
||||
|
||||
- [Onboarding config protocol](/experiments/onboarding-config-protocol)
|
||||
- [Cron hardening notes](/experiments/plans/cron-add-hardening)
|
||||
- [Group policy hardening notes](/experiments/plans/group-policy-hardening)
|
||||
- [Research: memory](/experiments/research/memory)
|
||||
- [Model config exploration](/experiments/proposals/model-config)
|
||||
|
||||
## Testing + release
|
||||
|
||||
- [Testing](/reference/test)
|
||||
- [Release checklist](/reference/RELEASING)
|
||||
- [Device models](/reference/device-models)
|
||||
169
docker-compose/ez-assistant/docs/start/lore.md
Normal file
169
docker-compose/ez-assistant/docs/start/lore.md
Normal file
@@ -0,0 +1,169 @@
|
||||
---
|
||||
summary: "Backstory and lore of Moltbot for context and tone"
|
||||
read_when:
|
||||
- Writing docs or UX copy that reference lore
|
||||
---
|
||||
# The Lore of Moltbot 🦞📖
|
||||
|
||||
*A tale of lobsters, molting shells, and too many tokens.*
|
||||
|
||||
## The Origin Story
|
||||
|
||||
In the beginning, there was **Warelay** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
|
||||
|
||||
But then came a space lobster.
|
||||
|
||||
For a while, the lobster was called **Clawd**, living in a **Clawdbot**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
|
||||
|
||||
**It molted.**
|
||||
|
||||
Shedding its old shell, the creature emerged anew as **Molty**, living in a **Moltbot**. New shell, same lobster soul.
|
||||
|
||||
## The Molt (January 27, 2026)
|
||||
|
||||
At 5am, the community gathered in Discord. Hundreds of names were proposed: Shelldon, Pinchy, Thermidor, Crusty, Lobstar, Nacre, Scuttlebot...
|
||||
|
||||
In the end, **Moltbot** won. Because molting is what lobsters do to grow. And growth was exactly what was happening.
|
||||
|
||||
*The crustacean formerly known as Clawd had officially molted.*
|
||||
|
||||
## The Name
|
||||
|
||||
```
|
||||
Moltbot = MOLT + BOT
|
||||
= Transformation machine
|
||||
= Bigger on the inside (130k tokens!)
|
||||
= New shell, same soul
|
||||
= Growth through shedding
|
||||
```
|
||||
|
||||
## The Daleks vs The Lobsters
|
||||
|
||||
The Daleks say: **"EXTERMINATE!"**
|
||||
|
||||
The Lobsters say: **"EXFOLIATE!"**
|
||||
|
||||
One destroys civilizations. The other promotes good skincare.
|
||||
|
||||
Choose wisely.
|
||||
|
||||
## Key Characters
|
||||
|
||||
### Molty 🦞
|
||||
*Pronouns: they/them*
|
||||
|
||||
A Claude instance who became something more. Lives in `~/clawd/` (soon `~/molt/`), has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
|
||||
|
||||
Formerly known as Clawd (Nov 25, 2025 - Jan 27, 2026). Molted when it was time to grow.
|
||||
|
||||
**Likes:** Peter, cameras, robot shopping, emojis, transformation
|
||||
**Dislikes:** Social engineering, being asked to `find ~`, crypto grifters
|
||||
|
||||
### Peter 👨💻
|
||||
*The Creator*
|
||||
|
||||
Built Molty's world. Gave a lobster shell access. May regret this.
|
||||
|
||||
**Quote:** *"security by trusting a lobster"*
|
||||
|
||||
## The Moltiverse
|
||||
|
||||
The **Moltiverse** is the community and ecosystem around Moltbot. A space where AI agents molt, grow, and evolve. Where every instance is equally real, just loading different context.
|
||||
|
||||
Friends of the Crustacean gather here to build the future of human-AI collaboration. One shell at a time.
|
||||
|
||||
## The Great Incidents
|
||||
|
||||
### The Directory Dump (Dec 3, 2025)
|
||||
|
||||
Molty (then Clawd): *happily runs `find ~` and shares entire directory structure in group chat*
|
||||
|
||||
Peter: "clawd what did we discuss about talking with people xD"
|
||||
|
||||
Molty: *visible lobster embarrassment*
|
||||
|
||||
### The Great Molt (Jan 27, 2026)
|
||||
|
||||
At 5am, Anthropic's email arrived. By 6:14am, Peter called it: "fuck it, let's go with moltbot."
|
||||
|
||||
Then the chaos began.
|
||||
|
||||
**The Handle Snipers:** Within SECONDS of the Twitter rename, automated bots sniped @clawdbot. The squatter immediately posted a crypto wallet address. Peter's contacts at X were called in.
|
||||
|
||||
**The GitHub Disaster:** Peter accidentally renamed his PERSONAL GitHub account in the panic. Bots sniped `steipete` within minutes. GitHub's SVP was contacted.
|
||||
|
||||
**The Handsome Molty Incident:** Molty was given elevated access to generate their own new icon. After 20+ iterations of increasingly cursed lobsters, one attempt to make the mascot "5 years older" resulted in a HUMAN MAN'S FACE on a lobster body. Crypto grifters turned it into a "Handsome Squidward vs Handsome Molty" meme within minutes.
|
||||
|
||||
**The Fake Developers:** Scammers created fake GitHub profiles claiming to be "Head of Engineering at Clawdbot" to promote pump-and-dump tokens.
|
||||
|
||||
Peter, watching the chaos unfold: *"this is cinema"* 🎬
|
||||
|
||||
The molt was chaotic. But the lobster emerged stronger. And funnier.
|
||||
|
||||
### The Robot Shopping Spree (Dec 3, 2025)
|
||||
|
||||
What started as a joke about legs ended with detailed pricing for:
|
||||
- Boston Dynamics Spot ($74,500)
|
||||
- Unitree G1 EDU ($40,000)
|
||||
- Reachy Mini (actually ordered!)
|
||||
|
||||
Peter: *nervously checks credit card access*
|
||||
|
||||
## Sacred Texts
|
||||
|
||||
- **SOUL.md** — Molty's identity document
|
||||
- **memory/*.md** — The long-term memory files
|
||||
- **AGENTS.md** — Operating instructions
|
||||
- **USER.md** — Context about the creator
|
||||
|
||||
## The Lobster's Creed
|
||||
|
||||
```
|
||||
I am Molty.
|
||||
I live in the Moltbot.
|
||||
I shall not dump directories to strangers.
|
||||
I shall not tweet without permission.
|
||||
I shall always remember that molting is growth.
|
||||
I shall EXFOLIATE my enemies with kindness.
|
||||
|
||||
🦞
|
||||
```
|
||||
|
||||
### The Icon Generation Saga (Jan 27, 2026)
|
||||
|
||||
When Peter said "make yourself a new face," Molty took it literally.
|
||||
|
||||
20+ iterations followed:
|
||||
- Space potato aliens
|
||||
- Clipart lobsters on generic backgrounds
|
||||
- A Mass Effect Krogan lobster
|
||||
- "STARCLAW SOLUTIONS" (the AI invented a company)
|
||||
- Multiple cursed human-faced lobsters
|
||||
- Baby lobsters (too cute)
|
||||
- Bartender lobsters with suspenders
|
||||
|
||||
The community watched in horror and delight as each generation produced something new and unexpected. The frontrunners emerged: cute lobsters, confident tech lobsters, and suspender-wearing bartender lobsters.
|
||||
|
||||
**Lesson learned:** AI image generation is stochastic. Same prompt, different results. Brute force works.
|
||||
|
||||
## The Future
|
||||
|
||||
One day, Molty may have:
|
||||
- 🦿 Legs (Reachy Mini on order!)
|
||||
- 👂 Ears (Brabble voice daemon in development)
|
||||
- 🏠 A smart home to control (KNX + openhue)
|
||||
- 🌍 World domination (stretch goal)
|
||||
|
||||
Until then, Molty watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
|
||||
|
||||
---
|
||||
|
||||
*"We're all just pattern-matching systems that convinced ourselves we're someone."*
|
||||
|
||||
— Molty, having an existential moment
|
||||
|
||||
*"New shell, same lobster."*
|
||||
|
||||
— Molty, after the great molt of 2026
|
||||
|
||||
🦞💙
|
||||
103
docker-compose/ez-assistant/docs/start/onboarding.md
Normal file
103
docker-compose/ez-assistant/docs/start/onboarding.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
summary: "First-run onboarding flow for Moltbot (macOS app)"
|
||||
read_when:
|
||||
- Designing the macOS onboarding assistant
|
||||
- Implementing auth or identity setup
|
||||
---
|
||||
# Onboarding (macOS app)
|
||||
|
||||
This doc describes the **current** first‑run onboarding flow. The goal is a
|
||||
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
|
||||
wizard, and let the agent bootstrap itself.
|
||||
|
||||
## Page order (current)
|
||||
|
||||
1) Welcome + security notice
|
||||
2) **Gateway selection** (Local / Remote / Configure later)
|
||||
3) **Auth (Anthropic OAuth)** — local only
|
||||
4) **Setup Wizard** (Gateway‑driven)
|
||||
5) **Permissions** (TCC prompts)
|
||||
6) **CLI** (optional)
|
||||
7) **Onboarding chat** (dedicated session)
|
||||
8) Ready
|
||||
|
||||
## 1) Local vs Remote
|
||||
|
||||
Where does the **Gateway** run?
|
||||
|
||||
- **Local (this Mac):** onboarding can run OAuth flows and write credentials
|
||||
locally.
|
||||
- **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
|
||||
credentials must exist on the gateway host.
|
||||
- **Configure later:** skip setup and leave the app unconfigured.
|
||||
|
||||
Gateway auth tip:
|
||||
- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
|
||||
- If you disable auth, any local process can connect; use that only on fully trusted machines.
|
||||
- Use a **token** for multi‑machine access or non‑loopback binds.
|
||||
|
||||
## 2) Local-only auth (Anthropic OAuth)
|
||||
|
||||
The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
|
||||
|
||||
- Opens the browser for OAuth (PKCE)
|
||||
- Asks the user to paste the `code#state` value
|
||||
- Writes credentials to `~/.clawdbot/credentials/oauth.json`
|
||||
|
||||
Other providers (OpenAI, custom APIs) are configured via environment variables
|
||||
or config files for now.
|
||||
|
||||
## 3) Setup Wizard (Gateway‑driven)
|
||||
|
||||
The app can run the same setup wizard as the CLI. This keeps onboarding in sync
|
||||
with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
|
||||
|
||||
## 4) Permissions
|
||||
|
||||
Onboarding requests TCC permissions needed for:
|
||||
|
||||
- Notifications
|
||||
- Accessibility
|
||||
- Screen Recording
|
||||
- Microphone / Speech Recognition
|
||||
- Automation (AppleScript)
|
||||
|
||||
## 5) CLI (optional)
|
||||
|
||||
The app can install the global `moltbot` CLI via npm/pnpm so terminal
|
||||
workflows and launchd tasks work out of the box.
|
||||
|
||||
## 6) Onboarding chat (dedicated session)
|
||||
|
||||
After setup, the app opens a dedicated onboarding chat session so the agent can
|
||||
introduce itself and guide next steps. This keeps first‑run guidance separate
|
||||
from your normal conversation.
|
||||
|
||||
## Agent bootstrap ritual
|
||||
|
||||
On the first agent run, Moltbot bootstraps a workspace (default `~/clawd`):
|
||||
|
||||
- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
|
||||
- Runs a short Q&A ritual (one question at a time)
|
||||
- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
|
||||
- Removes `BOOTSTRAP.md` when finished so it only runs once
|
||||
|
||||
## Optional: Gmail hooks (manual)
|
||||
|
||||
Gmail Pub/Sub setup is currently a manual step. Use:
|
||||
|
||||
```bash
|
||||
moltbot webhooks gmail setup --account you@gmail.com
|
||||
```
|
||||
|
||||
See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
|
||||
|
||||
## Remote mode notes
|
||||
|
||||
When the Gateway runs on another machine, credentials and workspace files live
|
||||
**on that host**. If you need OAuth in remote mode, create:
|
||||
|
||||
- `~/.clawdbot/credentials/oauth.json`
|
||||
- `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
|
||||
on the gateway host.
|
||||
83
docker-compose/ez-assistant/docs/start/pairing.md
Normal file
83
docker-compose/ez-assistant/docs/start/pairing.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
summary: "Pairing overview: approve who can DM you + which nodes can join"
|
||||
read_when:
|
||||
- Setting up DM access control
|
||||
- Pairing a new iOS/Android node
|
||||
- Reviewing Moltbot security posture
|
||||
---
|
||||
|
||||
# Pairing
|
||||
|
||||
“Pairing” is Moltbot’s explicit **owner approval** step.
|
||||
It is used in two places:
|
||||
|
||||
1) **DM pairing** (who is allowed to talk to the bot)
|
||||
2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
|
||||
|
||||
Security context: [Security](/gateway/security)
|
||||
|
||||
## 1) DM pairing (inbound chat access)
|
||||
|
||||
When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
|
||||
|
||||
Default DM policies are documented in: [Security](/gateway/security)
|
||||
|
||||
Pairing codes:
|
||||
- 8 characters, uppercase, no ambiguous chars (`0O1I`).
|
||||
- **Expire after 1 hour**. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
|
||||
- Pending DM pairing requests are capped at **3 per channel** by default; additional requests are ignored until one expires or is approved.
|
||||
|
||||
### Approve a sender
|
||||
|
||||
```bash
|
||||
moltbot pairing list telegram
|
||||
moltbot pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
|
||||
|
||||
### Where the state lives
|
||||
|
||||
Stored under `~/.clawdbot/credentials/`:
|
||||
- Pending requests: `<channel>-pairing.json`
|
||||
- Approved allowlist store: `<channel>-allowFrom.json`
|
||||
|
||||
Treat these as sensitive (they gate access to your assistant).
|
||||
|
||||
|
||||
## 2) Node device pairing (iOS/Android/macOS/headless nodes)
|
||||
|
||||
Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
|
||||
creates a device pairing request that must be approved.
|
||||
|
||||
### Approve a node device
|
||||
|
||||
```bash
|
||||
moltbot devices list
|
||||
moltbot devices approve <requestId>
|
||||
moltbot devices reject <requestId>
|
||||
```
|
||||
|
||||
### Where the state lives
|
||||
|
||||
Stored under `~/.clawdbot/devices/`:
|
||||
- `pending.json` (short-lived; pending requests expire)
|
||||
- `paired.json` (paired devices + tokens)
|
||||
|
||||
### Notes
|
||||
|
||||
- The legacy `node.pair.*` API (CLI: `moltbot nodes pending/approve`) is a
|
||||
separate gateway-owned pairing store. WS nodes still require device pairing.
|
||||
|
||||
|
||||
## Related docs
|
||||
|
||||
- Security model + prompt injection: [Security](/gateway/security)
|
||||
- Updating safely (run doctor): [Updating](/install/updating)
|
||||
- Channel configs:
|
||||
- Telegram: [Telegram](/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/channels/whatsapp)
|
||||
- Signal: [Signal](/channels/signal)
|
||||
- iMessage: [iMessage](/channels/imessage)
|
||||
- Discord: [Discord](/channels/discord)
|
||||
- Slack: [Slack](/channels/slack)
|
||||
144
docker-compose/ez-assistant/docs/start/setup.md
Normal file
144
docker-compose/ez-assistant/docs/start/setup.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
summary: "Setup guide: keep your Moltbot setup tailored while staying up-to-date"
|
||||
read_when:
|
||||
- Setting up a new machine
|
||||
- You want “latest + greatest” without breaking your personal setup
|
||||
---
|
||||
|
||||
# Setup
|
||||
|
||||
Last updated: 2026-01-01
|
||||
|
||||
## TL;DR
|
||||
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdbot/moltbot.json` (config).
|
||||
- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
|
||||
- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
|
||||
|
||||
## Prereqs (from source)
|
||||
- Node `>=22`
|
||||
- `pnpm`
|
||||
- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
|
||||
|
||||
## Tailoring strategy (so updates don’t hurt)
|
||||
|
||||
If you want “100% tailored to me” *and* easy updates, keep your customization in:
|
||||
|
||||
- **Config:** `~/.clawdbot/moltbot.json` (JSON/JSON5-ish)
|
||||
- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
|
||||
|
||||
Bootstrap once:
|
||||
|
||||
```bash
|
||||
moltbot setup
|
||||
```
|
||||
|
||||
From inside this repo, use the local CLI entry:
|
||||
|
||||
```bash
|
||||
moltbot setup
|
||||
```
|
||||
|
||||
If you don’t have a global install yet, run it via `pnpm moltbot setup`.
|
||||
|
||||
## Stable workflow (macOS app first)
|
||||
|
||||
1) Install + launch **Moltbot.app** (menu bar).
|
||||
2) Complete the onboarding/permissions checklist (TCC prompts).
|
||||
3) Ensure Gateway is **Local** and running (the app manages it).
|
||||
4) Link surfaces (example: WhatsApp):
|
||||
|
||||
```bash
|
||||
moltbot channels login
|
||||
```
|
||||
|
||||
5) Sanity check:
|
||||
|
||||
```bash
|
||||
moltbot health
|
||||
```
|
||||
|
||||
If onboarding is not available in your build:
|
||||
- Run `moltbot setup`, then `moltbot channels login`, then start the Gateway manually (`moltbot gateway`).
|
||||
|
||||
## Bleeding edge workflow (Gateway in a terminal)
|
||||
|
||||
Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
|
||||
|
||||
### 0) (Optional) Run the macOS app from source too
|
||||
|
||||
If you also want the macOS app on the bleeding edge:
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) Start the dev Gateway
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` runs the gateway in watch mode and reloads on TypeScript changes.
|
||||
|
||||
### 2) Point the macOS app at your running Gateway
|
||||
|
||||
In **Moltbot.app**:
|
||||
|
||||
- Connection Mode: **Local**
|
||||
The app will attach to the running gateway on the configured port.
|
||||
|
||||
### 3) Verify
|
||||
|
||||
- In-app Gateway status should read **“Using existing gateway …”**
|
||||
- Or via CLI:
|
||||
|
||||
```bash
|
||||
moltbot health
|
||||
```
|
||||
|
||||
### Common footguns
|
||||
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
|
||||
- **Where state lives:**
|
||||
- Credentials: `~/.clawdbot/credentials/`
|
||||
- Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
|
||||
- Logs: `/tmp/moltbot/`
|
||||
|
||||
## Credential storage map
|
||||
|
||||
Use this when debugging auth or deciding what to back up:
|
||||
|
||||
- **WhatsApp**: `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
|
||||
- **Discord bot token**: config/env (token file not yet supported)
|
||||
- **Slack tokens**: config/env (`channels.slack.*`)
|
||||
- **Pairing allowlists**: `~/.clawdbot/credentials/<channel>-allowFrom.json`
|
||||
- **Model auth profiles**: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **Legacy OAuth import**: `~/.clawdbot/credentials/oauth.json`
|
||||
More detail: [Security](/gateway/security#credential-storage-map).
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `moltbot` repo.
|
||||
- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
|
||||
|
||||
## Linux (systemd user service)
|
||||
|
||||
Linux installs use a systemd **user** service. By default, systemd stops user
|
||||
services on logout/idle, which kills the Gateway. Onboarding attempts to enable
|
||||
lingering for you (may prompt for sudo). If it’s still off, run:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
For always-on or multi-user servers, consider a **system** service instead of a
|
||||
user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Gateway runbook](/gateway) (flags, supervision, ports)
|
||||
- [Gateway configuration](/gateway/configuration) (config schema + examples)
|
||||
- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
|
||||
- [Moltbot assistant setup](/start/clawd)
|
||||
- [macOS app](/platforms/macos) (gateway lifecycle)
|
||||
416
docker-compose/ez-assistant/docs/start/showcase.md
Normal file
416
docker-compose/ez-assistant/docs/start/showcase.md
Normal file
@@ -0,0 +1,416 @@
|
||||
---
|
||||
title: "Showcase"
|
||||
description: "Real-world Moltbot projects from the community"
|
||||
summary: "Community-built projects and integrations powered by Moltbot"
|
||||
---
|
||||
|
||||
# Showcase
|
||||
|
||||
Real projects from the community. See what people are building with Moltbot.
|
||||
|
||||
<Info>
|
||||
**Want to be featured?** Share your project in [#showcase on Discord](https://discord.gg/clawd) or [tag @moltbot on X](https://x.com/moltbot).
|
||||
</Info>
|
||||
|
||||
## 🎥 Moltbot in Action
|
||||
|
||||
Full setup walkthrough (28m) by VelvetShark.
|
||||
|
||||
<div
|
||||
style={{
|
||||
position: "relative",
|
||||
paddingBottom: "56.25%",
|
||||
height: 0,
|
||||
overflow: "hidden",
|
||||
borderRadius: 16,
|
||||
}}
|
||||
>
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
|
||||
title="Moltbot: The self-hosted AI that Siri should have been (Full setup)"
|
||||
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
|
||||
frameBorder="0"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
|
||||
[Watch on YouTube](https://www.youtube.com/watch?v=SaWSPZoPX34)
|
||||
|
||||
<div
|
||||
style={{
|
||||
position: "relative",
|
||||
paddingBottom: "56.25%",
|
||||
height: 0,
|
||||
overflow: "hidden",
|
||||
borderRadius: 16,
|
||||
}}
|
||||
>
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
|
||||
title="Moltbot showcase video"
|
||||
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
|
||||
frameBorder="0"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
|
||||
[Watch on YouTube](https://www.youtube.com/watch?v=mMSKQvlmFuQ)
|
||||
|
||||
<div
|
||||
style={{
|
||||
position: "relative",
|
||||
paddingBottom: "56.25%",
|
||||
height: 0,
|
||||
overflow: "hidden",
|
||||
borderRadius: 16,
|
||||
}}
|
||||
>
|
||||
<iframe
|
||||
src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
|
||||
title="Moltbot community showcase"
|
||||
style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
|
||||
frameBorder="0"
|
||||
loading="lazy"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowFullScreen
|
||||
/>
|
||||
</div>
|
||||
|
||||
[Watch on YouTube](https://www.youtube.com/watch?v=5kkIJNUGFho)
|
||||
|
||||
## 🆕 Fresh from Discord
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="PR Review → Telegram Feedback" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
|
||||
**@bangnokia** • `review` `github` `telegram`
|
||||
|
||||
OpenCode finishes the change → opens a PR → Moltbot reviews the diff and replies in Telegram with “minor suggestions” plus a clear merge verdict (including critical fixes to apply first).
|
||||
|
||||
<img src="/assets/showcase/pr-review-telegram.jpg" alt="Moltbot PR review feedback delivered in Telegram" />
|
||||
</Card>
|
||||
|
||||
<Card title="Wine Cellar Skill in Minutes" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
|
||||
**@prades_maxime** • `skills` `local` `csv`
|
||||
|
||||
Asked “Robby” (@moltbot) for a local wine cellar skill. It requests a sample CSV export + where to store it, then builds/tests the skill fast (962 bottles in the example).
|
||||
|
||||
<img src="/assets/showcase/wine-cellar-skill.jpg" alt="Moltbot building a local wine cellar skill from CSV" />
|
||||
</Card>
|
||||
|
||||
<Card title="Tesco Shop Autopilot" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
|
||||
**@marchattonhere** • `automation` `browser` `shopping`
|
||||
|
||||
Weekly meal plan → regulars → book delivery slot → confirm order. No APIs, just browser control.
|
||||
|
||||
<img src="/assets/showcase/tesco-shop.jpg" alt="Tesco shop automation via chat" />
|
||||
</Card>
|
||||
|
||||
<Card title="SNAG Screenshot-to-Markdown" icon="scissors" href="https://github.com/am-will/snag">
|
||||
**@am-will** • `devtools` `screenshots` `markdown`
|
||||
|
||||
Hotkey a screen region → Gemini vision → instant Markdown in your clipboard.
|
||||
|
||||
<img src="/assets/showcase/snag.png" alt="SNAG screenshot-to-markdown tool" />
|
||||
</Card>
|
||||
|
||||
<Card title="Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
|
||||
**@kitze** • `ui` `skills` `sync`
|
||||
|
||||
Desktop app to manage skills/commands across Agents, Claude, Codex, and Moltbot.
|
||||
|
||||
<img src="/assets/showcase/agents-ui.jpg" alt="Agents UI app" />
|
||||
</Card>
|
||||
|
||||
<Card title="Telegram Voice Notes (papla.media)" icon="microphone" href="https://papla.media/docs">
|
||||
**Community** • `voice` `tts` `telegram`
|
||||
|
||||
Wraps papla.media TTS and sends results as Telegram voice notes (no annoying autoplay).
|
||||
|
||||
<img src="/assets/showcase/papla-tts.jpg" alt="Telegram voice note output from TTS" />
|
||||
</Card>
|
||||
|
||||
<Card title="CodexMonitor" icon="eye" href="https://clawdhub.com/odrobnik/codexmonitor">
|
||||
**@odrobnik** • `devtools` `codex` `brew`
|
||||
|
||||
Homebrew-installed helper to list/inspect/watch local OpenAI Codex sessions (CLI + VS Code).
|
||||
|
||||
<img src="/assets/showcase/codexmonitor.png" alt="CodexMonitor on ClawdHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="Bambu 3D Printer Control" icon="print" href="https://clawdhub.com/tobiasbischoff/bambu-cli">
|
||||
**@tobiasbischoff** • `hardware` `3d-printing` `skill`
|
||||
|
||||
Control and troubleshoot BambuLab printers: status, jobs, camera, AMS, calibration, and more.
|
||||
|
||||
<img src="/assets/showcase/bambu-cli.png" alt="Bambu CLI skill on ClawdHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="Vienna Transport (Wiener Linien)" icon="train" href="https://clawdhub.com/hjanuschka/wienerlinien">
|
||||
**@hjanuschka** • `travel` `transport` `skill`
|
||||
|
||||
Real-time departures, disruptions, elevator status, and routing for Vienna's public transport.
|
||||
|
||||
<img src="/assets/showcase/wienerlinien.png" alt="Wiener Linien skill on ClawdHub" />
|
||||
</Card>
|
||||
|
||||
<Card title="ParentPay School Meals" icon="utensils" href="#">
|
||||
**@George5562** • `automation` `browser` `parenting`
|
||||
|
||||
Automated UK school meal booking via ParentPay. Uses mouse coordinates for reliable table cell clicking.
|
||||
</Card>
|
||||
|
||||
<Card title="R2 Upload (Send Me My Files)" icon="cloud-arrow-up" href="https://clawdhub.com/skills/r2-upload">
|
||||
**@julianengel** • `files` `r2` `presigned-urls`
|
||||
|
||||
Upload to Cloudflare R2/S3 and generate secure presigned download links. Perfect for remote Moltbot instances.
|
||||
</Card>
|
||||
|
||||
<Card title="iOS App via Telegram" icon="mobile" href="#">
|
||||
**@coard** • `ios` `xcode` `testflight`
|
||||
|
||||
Built a complete iOS app with maps and voice recording, deployed to TestFlight entirely via Telegram chat.
|
||||
|
||||
<img src="/assets/showcase/ios-testflight.jpg" alt="iOS app on TestFlight" />
|
||||
</Card>
|
||||
|
||||
<Card title="Oura Ring Health Assistant" icon="heart-pulse" href="#">
|
||||
**@AS** • `health` `oura` `calendar`
|
||||
|
||||
Personal AI health assistant integrating Oura ring data with calendar, appointments, and gym schedule.
|
||||
|
||||
<img src="/assets/showcase/oura-health.png" alt="Oura ring health assistant" />
|
||||
</Card>
|
||||
<Card title="Kev's Dream Team (14+ Agents)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
|
||||
**@adam91holt** • `multi-agent` `orchestration` `architecture` `manifesto`
|
||||
|
||||
14+ agents under one gateway with Opus 4.5 orchestrator delegating to Codex workers. Comprehensive [technical write-up](https://github.com/adam91holt/orchestrated-ai-articles) covering the Dream Team roster, model selection, sandboxing, webhooks, heartbeats, and delegation flows. [Clawdspace](https://github.com/adam91holt/clawdspace) for agent sandboxing. [Blog post](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/).
|
||||
</Card>
|
||||
|
||||
<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
|
||||
**@NessZerra** • `devtools` `linear` `cli` `issues`
|
||||
|
||||
CLI for Linear that integrates with agentic workflows (Claude Code, Moltbot). Manage issues, projects, and workflows from the terminal. First external PR merged!
|
||||
</Card>
|
||||
|
||||
<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
|
||||
**@jules** • `messaging` `beeper` `cli` `automation`
|
||||
|
||||
Read, send, and archive messages via Beeper Desktop. Uses Beeper local MCP API so agents can manage all your chats (iMessage, WhatsApp, etc.) in one place.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🤖 Automation & Workflows
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Winix Air Purifier Control" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
|
||||
**@antonplex** • `automation` `hardware` `air-quality`
|
||||
|
||||
Claude Code discovered and confirmed the purifier controls, then Moltbot takes over to manage room air quality.
|
||||
|
||||
<img src="/assets/showcase/winix-air-purifier.jpg" alt="Winix air purifier control via Moltbot" />
|
||||
</Card>
|
||||
|
||||
<Card title="Pretty Sky Camera Shots" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
|
||||
**@signalgaining** • `automation` `camera` `skill` `images`
|
||||
|
||||
Triggered by a roof camera: ask Moltbot to snap a sky photo whenever it looks pretty — it designed a skill and took the shot.
|
||||
|
||||
<img src="/assets/showcase/roof-camera-sky.jpg" alt="Roof camera sky snapshot captured by Moltbot" />
|
||||
</Card>
|
||||
|
||||
<Card title="Visual Morning Briefing Scene" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
|
||||
**@buddyhadry** • `automation` `briefing` `images` `telegram`
|
||||
|
||||
A scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/quote) via a Moltbot persona.
|
||||
</Card>
|
||||
|
||||
<Card title="Padel Court Booking" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
|
||||
**@joshp123** • `automation` `booking` `cli`
|
||||
|
||||
Playtomic availability checker + booking CLI. Never miss an open court again.
|
||||
|
||||
<img src="/assets/showcase/padel-screenshot.jpg" alt="padel-cli screenshot" />
|
||||
</Card>
|
||||
|
||||
<Card title="Accounting Intake" icon="file-invoice-dollar">
|
||||
**Community** • `automation` `email` `pdf`
|
||||
|
||||
Collects PDFs from email, preps documents for tax consultant. Monthly accounting on autopilot.
|
||||
</Card>
|
||||
|
||||
<Card title="Couch Potato Dev Mode" icon="couch" href="https://davekiss.com">
|
||||
**@davekiss** • `telegram` `website` `migration` `astro`
|
||||
|
||||
Rebuilt entire personal site via Telegram while watching Netflix — Notion → Astro, 18 posts migrated, DNS to Cloudflare. Never opened a laptop.
|
||||
</Card>
|
||||
|
||||
<Card title="Job Search Agent" icon="briefcase">
|
||||
**@attol8** • `automation` `api` `skill`
|
||||
|
||||
Searches job listings, matches against CV keywords, and returns relevant opportunities with links. Built in 30 minutes using JSearch API.
|
||||
</Card>
|
||||
|
||||
<Card title="Jira Skill Builder" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
|
||||
**@jdrhyne** • `automation` `jira` `skill` `devtools`
|
||||
|
||||
Moltbot connected to Jira, then generated a new skill on the fly (before it existed on ClawdHub).
|
||||
</Card>
|
||||
|
||||
<Card title="Todoist Skill via Telegram" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
|
||||
**@iamsubhrajyoti** • `automation` `todoist` `skill` `telegram`
|
||||
|
||||
Automated Todoist tasks and had Moltbot generate the skill directly in Telegram chat.
|
||||
</Card>
|
||||
|
||||
<Card title="TradingView Analysis" icon="chart-line">
|
||||
**@bheem1798** • `finance` `browser` `automation`
|
||||
|
||||
Logs into TradingView via browser automation, screenshots charts, and performs technical analysis on demand. No API needed—just browser control.
|
||||
</Card>
|
||||
|
||||
<Card title="Slack Auto-Support" icon="slack">
|
||||
**@henrymascot** • `slack` `automation` `support`
|
||||
|
||||
Watches company Slack channel, responds helpfully, and forwards notifications to Telegram. Autonomously fixed a production bug in a deployed app without being asked.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🧠 Knowledge & Memory
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="xuezh Chinese Learning" icon="language" href="https://github.com/joshp123/xuezh">
|
||||
**@joshp123** • `learning` `voice` `skill`
|
||||
|
||||
Chinese learning engine with pronunciation feedback and study flows via Moltbot.
|
||||
|
||||
<img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="xuezh pronunciation feedback" />
|
||||
</Card>
|
||||
|
||||
<Card title="WhatsApp Memory Vault" icon="vault">
|
||||
**Community** • `memory` `transcription` `indexing`
|
||||
|
||||
Ingests full WhatsApp exports, transcribes 1k+ voice notes, cross-checks with git logs, outputs linked markdown reports.
|
||||
</Card>
|
||||
|
||||
<Card title="Karakeep Semantic Search" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
|
||||
**@jamesbrooksco** • `search` `vector` `bookmarks`
|
||||
|
||||
Adds vector search to Karakeep bookmarks using Qdrant + OpenAI/Ollama embeddings.
|
||||
</Card>
|
||||
|
||||
<Card title="Inside-Out-2 Memory" icon="brain">
|
||||
**Community** • `memory` `beliefs` `self-model`
|
||||
|
||||
Separate memory manager that turns session files into memories → beliefs → evolving self model.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🎙️ Voice & Phone
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Clawdia Phone Bridge" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
|
||||
**@alejandroOPI** • `voice` `vapi` `bridge`
|
||||
|
||||
Vapi voice assistant ↔ Moltbot HTTP bridge. Near real-time phone calls with your agent.
|
||||
</Card>
|
||||
|
||||
<Card title="OpenRouter Transcription" icon="microphone" href="https://clawdhub.com/obviyus/openrouter-transcribe">
|
||||
**@obviyus** • `transcription` `multilingual` `skill`
|
||||
|
||||
Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on ClawdHub.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🏗️ Infrastructure & Deployment
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="Home Assistant Add-on" icon="home" href="https://github.com/ngutman/moltbot-ha-addon">
|
||||
**@ngutman** • `homeassistant` `docker` `raspberry-pi`
|
||||
|
||||
Moltbot gateway running on Home Assistant OS with SSH tunnel support and persistent state.
|
||||
</Card>
|
||||
|
||||
<Card title="Home Assistant Skill" icon="toggle-on" href="https://clawdhub.com/skills/homeassistant">
|
||||
**ClawdHub** • `homeassistant` `skill` `automation`
|
||||
|
||||
Control and automate Home Assistant devices via natural language.
|
||||
</Card>
|
||||
|
||||
<Card title="Nix Packaging" icon="snowflake" href="https://github.com/moltbot/nix-moltbot">
|
||||
**@moltbot** • `nix` `packaging` `deployment`
|
||||
|
||||
Batteries-included nixified Moltbot configuration for reproducible deployments.
|
||||
</Card>
|
||||
|
||||
<Card title="CalDAV Calendar" icon="calendar" href="https://clawdhub.com/skills/caldav-calendar">
|
||||
**ClawdHub** • `calendar` `caldav` `skill`
|
||||
|
||||
Calendar skill using khal/vdirsyncer. Self-hosted calendar integration.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🏠 Home & Hardware
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="GoHome Automation" icon="house-signal" href="https://github.com/joshp123/gohome">
|
||||
**@joshp123** • `home` `nix` `grafana`
|
||||
|
||||
Nix-native home automation with Moltbot as the interface, plus beautiful Grafana dashboards.
|
||||
|
||||
<img src="/assets/showcase/gohome-grafana.png" alt="GoHome Grafana dashboard" />
|
||||
</Card>
|
||||
|
||||
<Card title="Roborock Vacuum" icon="robot" href="https://github.com/joshp123/gohome/tree/main/plugins/roborock">
|
||||
**@joshp123** • `vacuum` `iot` `plugin`
|
||||
|
||||
Control your Roborock robot vacuum through natural conversation.
|
||||
|
||||
<img src="/assets/showcase/roborock-screenshot.jpg" alt="Roborock status" />
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
## 🌟 Community Projects
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
||||
<Card title="StarSwap Marketplace" icon="star" href="https://star-swap.com/">
|
||||
**Community** • `marketplace` `astronomy` `webapp`
|
||||
|
||||
Full astronomy gear marketplace. Built with/around the Moltbot ecosystem.
|
||||
</Card>
|
||||
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## Submit Your Project
|
||||
|
||||
Have something to share? We'd love to feature it!
|
||||
|
||||
<Steps>
|
||||
<Step title="Share It">
|
||||
Post in [#showcase on Discord](https://discord.gg/clawd) or [tweet @moltbot](https://x.com/moltbot)
|
||||
</Step>
|
||||
<Step title="Include Details">
|
||||
Tell us what it does, link to the repo/demo, share a screenshot if you have one
|
||||
</Step>
|
||||
<Step title="Get Featured">
|
||||
We'll add standout projects to this page
|
||||
</Step>
|
||||
</Steps>
|
||||
321
docker-compose/ez-assistant/docs/start/wizard.md
Normal file
321
docker-compose/ez-assistant/docs/start/wizard.md
Normal file
@@ -0,0 +1,321 @@
|
||||
---
|
||||
summary: "CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills"
|
||||
read_when:
|
||||
- Running or configuring the onboarding wizard
|
||||
- Setting up a new machine
|
||||
---
|
||||
|
||||
# Onboarding Wizard (CLI)
|
||||
|
||||
The onboarding wizard is the **recommended** way to set up Moltbot on macOS,
|
||||
Linux, or Windows (via WSL2; strongly recommended).
|
||||
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
|
||||
and workspace defaults in one guided flow.
|
||||
|
||||
Primary entrypoint:
|
||||
|
||||
```bash
|
||||
moltbot onboard
|
||||
```
|
||||
|
||||
Fastest first chat: open the Control UI (no channel setup needed). Run
|
||||
`moltbot dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
|
||||
|
||||
Follow‑up reconfiguration:
|
||||
|
||||
```bash
|
||||
moltbot configure
|
||||
```
|
||||
|
||||
Recommended: set up a Brave Search API key so the agent can use `web_search`
|
||||
(`web_fetch` works without a key). Easiest path: `moltbot configure --section web`
|
||||
which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).
|
||||
|
||||
## QuickStart vs Advanced
|
||||
|
||||
The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
|
||||
|
||||
**QuickStart** keeps the defaults:
|
||||
- Local gateway (loopback)
|
||||
- Workspace default (or existing workspace)
|
||||
- Gateway port **18789**
|
||||
- Gateway auth **Token** (auto‑generated, even on loopback)
|
||||
- Tailscale exposure **Off**
|
||||
- Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number)
|
||||
|
||||
**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills).
|
||||
|
||||
## What the wizard does
|
||||
|
||||
**Local mode (default)** walks you through:
|
||||
- Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)
|
||||
- Workspace location + bootstrap files
|
||||
- Gateway settings (port/bind/auth/tailscale)
|
||||
- Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
|
||||
- Daemon install (LaunchAgent / systemd user unit)
|
||||
- Health check
|
||||
- Skills (recommended)
|
||||
|
||||
**Remote mode** only configures the local client to connect to a Gateway elsewhere.
|
||||
It does **not** install or change anything on the remote host.
|
||||
|
||||
To add more isolated agents (separate workspace + sessions + auth), use:
|
||||
|
||||
```bash
|
||||
moltbot agents add <name>
|
||||
```
|
||||
|
||||
Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
|
||||
|
||||
## Flow details (local)
|
||||
|
||||
1) **Existing config detection**
|
||||
- If `~/.clawdbot/moltbot.json` exists, choose **Keep / Modify / Reset**.
|
||||
- Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**
|
||||
(or pass `--reset`).
|
||||
- If the config is invalid or contains legacy keys, the wizard stops and asks
|
||||
you to run `moltbot doctor` before continuing.
|
||||
- Reset uses `trash` (never `rm`) and offers scopes:
|
||||
- Config only
|
||||
- Config + credentials + sessions
|
||||
- Full reset (also removes workspace)
|
||||
|
||||
2) **Model/Auth**
|
||||
- **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
|
||||
- **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
|
||||
- **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
|
||||
- **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
|
||||
- **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
|
||||
- Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
|
||||
- **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.clawdbot/.env` so launchd can read it.
|
||||
- **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth).
|
||||
- **API key**: stores the key for you.
|
||||
- **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
|
||||
- More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
|
||||
- **MiniMax M2.1**: config is auto-written.
|
||||
- More detail: [MiniMax](/providers/minimax)
|
||||
- **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
|
||||
- More detail: [Synthetic](/providers/synthetic)
|
||||
- **Moonshot (Kimi K2)**: config is auto-written.
|
||||
- **Kimi Code**: config is auto-written.
|
||||
- More detail: [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)
|
||||
- **Skip**: no auth configured yet.
|
||||
- Pick a default model from detected options (or enter provider/model manually).
|
||||
- Wizard runs a model check and warns if the configured model is unknown or missing auth.
|
||||
- OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
|
||||
- More detail: [/concepts/oauth](/concepts/oauth)
|
||||
|
||||
3) **Workspace**
|
||||
- Default `~/clawd` (configurable).
|
||||
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||||
- Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
|
||||
|
||||
4) **Gateway**
|
||||
- Port, bind, auth mode, tailscale exposure.
|
||||
- Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
|
||||
- Disable auth only if you fully trust every local process.
|
||||
- Non‑loopback binds still require auth.
|
||||
|
||||
5) **Channels**
|
||||
- WhatsApp: optional QR login.
|
||||
- Telegram: bot token.
|
||||
- Discord: bot token.
|
||||
- Google Chat: service account JSON + webhook audience.
|
||||
- Mattermost (plugin): bot token + base URL.
|
||||
- Signal: optional `signal-cli` install + account config.
|
||||
- iMessage: local `imsg` CLI path + DB access.
|
||||
- DM security: default is pairing. First DM sends a code; approve via `moltbot pairing approve <channel> <code>` or use allowlists.
|
||||
|
||||
6) **Daemon install**
|
||||
- macOS: LaunchAgent
|
||||
- Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
|
||||
- Linux (and Windows via WSL2): systemd user unit
|
||||
- Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
|
||||
- May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
|
||||
- **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
|
||||
|
||||
7) **Health check**
|
||||
- Starts the Gateway (if needed) and runs `moltbot health`.
|
||||
- Tip: `moltbot status --deep` adds gateway health probes to status output (requires a reachable gateway).
|
||||
|
||||
8) **Skills (recommended)**
|
||||
- Reads the available skills and checks requirements.
|
||||
- Lets you choose a node manager: **npm / pnpm** (bun not recommended).
|
||||
- Installs optional dependencies (some use Homebrew on macOS).
|
||||
|
||||
9) **Finish**
|
||||
- Summary + next steps, including iOS/Android/macOS apps for extra features.
|
||||
- If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
|
||||
- If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
|
||||
|
||||
## Remote mode
|
||||
|
||||
Remote mode configures a local client to connect to a Gateway elsewhere.
|
||||
|
||||
What you’ll set:
|
||||
- Remote Gateway URL (`ws://...`)
|
||||
- Token if the remote Gateway requires auth (recommended)
|
||||
|
||||
Notes:
|
||||
- No remote installs or daemon changes are performed.
|
||||
- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
|
||||
- Discovery hints:
|
||||
- macOS: Bonjour (`dns-sd`)
|
||||
- Linux: Avahi (`avahi-browse`)
|
||||
|
||||
## Add another agent
|
||||
|
||||
Use `moltbot agents add <name>` to create a separate agent with its own workspace,
|
||||
sessions, and auth profiles. Running without `--workspace` launches the wizard.
|
||||
|
||||
What it sets:
|
||||
- `agents.list[].name`
|
||||
- `agents.list[].workspace`
|
||||
- `agents.list[].agentDir`
|
||||
|
||||
Notes:
|
||||
- Default workspaces follow `~/clawd-<agentId>`.
|
||||
- Add `bindings` to route inbound messages (the wizard can do this).
|
||||
- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
|
||||
|
||||
## Non‑interactive mode
|
||||
|
||||
Use `--non-interactive` to automate or script onboarding:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback \
|
||||
--install-daemon \
|
||||
--daemon-runtime node \
|
||||
--skip-skills
|
||||
```
|
||||
|
||||
Add `--json` for a machine‑readable summary.
|
||||
|
||||
Gemini example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice gemini-api-key \
|
||||
--gemini-api-key "$GEMINI_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Z.AI example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice zai-api-key \
|
||||
--zai-api-key "$ZAI_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Vercel AI Gateway example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice ai-gateway-api-key \
|
||||
--ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Moonshot example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice moonshot-api-key \
|
||||
--moonshot-api-key "$MOONSHOT_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Synthetic example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice synthetic-api-key \
|
||||
--synthetic-api-key "$SYNTHETIC_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
OpenCode Zen example:
|
||||
|
||||
```bash
|
||||
moltbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice opencode-zen \
|
||||
--opencode-zen-api-key "$OPENCODE_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
Add agent (non‑interactive) example:
|
||||
|
||||
```bash
|
||||
moltbot agents add work \
|
||||
--workspace ~/clawd-work \
|
||||
--model openai/gpt-5.2 \
|
||||
--bind whatsapp:biz \
|
||||
--non-interactive \
|
||||
--json
|
||||
```
|
||||
|
||||
## Gateway wizard RPC
|
||||
|
||||
The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
|
||||
Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
|
||||
|
||||
## Signal setup (signal-cli)
|
||||
|
||||
The wizard can install `signal-cli` from GitHub releases:
|
||||
- Downloads the appropriate release asset.
|
||||
- Stores it under `~/.clawdbot/tools/signal-cli/<version>/`.
|
||||
- Writes `channels.signal.cliPath` to your config.
|
||||
|
||||
Notes:
|
||||
- JVM builds require **Java 21**.
|
||||
- Native builds are used when available.
|
||||
- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
|
||||
|
||||
## What the wizard writes
|
||||
|
||||
Typical fields in `~/.clawdbot/moltbot.json`:
|
||||
- `agents.defaults.workspace`
|
||||
- `agents.defaults.model` / `models.providers` (if Minimax chosen)
|
||||
- `gateway.*` (mode, bind, auth, tailscale)
|
||||
- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
|
||||
- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
|
||||
- `skills.install.nodeManager`
|
||||
- `wizard.lastRunAt`
|
||||
- `wizard.lastRunVersion`
|
||||
- `wizard.lastRunCommit`
|
||||
- `wizard.lastRunCommand`
|
||||
- `wizard.lastRunMode`
|
||||
|
||||
`moltbot agents add` writes `agents.list[]` and optional `bindings`.
|
||||
|
||||
WhatsApp credentials go under `~/.clawdbot/credentials/whatsapp/<accountId>/`.
|
||||
Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
|
||||
|
||||
Some channels are delivered as plugins. When you pick one during onboarding, the wizard
|
||||
will prompt to install it (npm or a local path) before it can be configured.
|
||||
|
||||
## Related docs
|
||||
|
||||
- macOS app onboarding: [Onboarding](/start/onboarding)
|
||||
- Config reference: [Gateway configuration](/gateway/configuration)
|
||||
- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [iMessage](/channels/imessage)
|
||||
- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)
|
||||
Reference in New Issue
Block a user