kelin/EZ-Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add ez-assistant and kerberos service folders

Browse Source
This commit is contained in:
kelin
2026-02-11 14:56:03 -05:00
parent e4e8ae1b87
commit 9ccfb36923
4471 changed files with 746463 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docker-compose/ez-assistant/docs/install/ansible.md Normal file
View File

@@ -0,0 +1,205 @@
---
summary: "Automated, hardened Moltbot installation with Ansible, Tailscale VPN, and firewall isolation"
read_when:
- You want automated server deployment with security hardening
- You need firewall-isolated setup with VPN access
- You're deploying to remote Debian/Ubuntu servers
---
# Ansible Installation
The recommended way to deploy Moltbot to production servers is via **[moltbot-ansible](https://github.com/moltbot/moltbot-ansible)** — an automated installer with security-first architecture.
## Quick Start
One-command install:
```bash
curl -fsSL https://raw.githubusercontent.com/moltbot/moltbot-ansible/main/install.sh | bash
```
> **📦 Full guide: [github.com/moltbot/moltbot-ansible](https://github.com/moltbot/moltbot-ansible)**
>
> The moltbot-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.
## What You Get
- 🔒 **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible)
- 🔐 **Tailscale VPN**: Secure remote access without exposing services publicly
- 🐳 **Docker**: Isolated sandbox containers, localhost-only bindings
- 🛡️ **Defense in depth**: 4-layer security architecture
- 🚀 **One-command setup**: Complete deployment in minutes
- 🔧 **Systemd integration**: Auto-start on boot with hardening
## Requirements
- **OS**: Debian 11+ or Ubuntu 20.04+
- **Access**: Root or sudo privileges
- **Network**: Internet connection for package installation
- **Ansible**: 2.14+ (installed automatically by quick-start script)
## What Gets Installed
The Ansible playbook installs and configures:
1. **Tailscale** (mesh VPN for secure remote access)
2. **UFW firewall** (SSH + Tailscale ports only)
3. **Docker CE + Compose V2** (for agent sandboxes)
4. **Node.js 22.x + pnpm** (runtime dependencies)
5. **Moltbot** (host-based, not containerized)
6. **Systemd service** (auto-start with security hardening)
Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
## Post-Install Setup
After installation completes, switch to the moltbot user:
```bash
sudo -i -u moltbot
```
The post-install script will guide you through:
1. **Onboarding wizard**: Configure Moltbot settings
2. **Provider login**: Connect WhatsApp/Telegram/Discord/Signal
3. **Gateway testing**: Verify the installation
4. **Tailscale setup**: Connect to your VPN mesh
### Quick commands
```bash
# Check service status
sudo systemctl status moltbot
# View live logs
sudo journalctl -u moltbot -f
# Restart gateway
sudo systemctl restart moltbot
# Provider login (run as moltbot user)
sudo -i -u moltbot
moltbot channels login
```
## Security Architecture
### 4-Layer Defense
1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly
2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh
3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure
4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user
### Verification
Test external attack surface:
```bash
nmap -p- YOUR_SERVER_IP
```
Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down.
### Docker Availability
Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
## Manual Installation
If you prefer manual control over the automation:
```bash
# 1. Install prerequisites
sudo apt update && sudo apt install -y ansible git
# 2. Clone repository
git clone https://github.com/moltbot/moltbot-ansible.git
cd moltbot-ansible
# 3. Install Ansible collections
ansible-galaxy collection install -r requirements.yml
# 4. Run playbook
./run-playbook.sh
# Or run directly (then manually execute /tmp/moltbot-setup.sh after)
# ansible-playbook playbook.yml --ask-become-pass
```
## Updating Moltbot
The Ansible installer sets up Moltbot for manual updates. See [Updating](/install/updating) for the standard update flow.
To re-run the Ansible playbook (e.g., for configuration changes):
```bash
cd moltbot-ansible
./run-playbook.sh
```
Note: This is idempotent and safe to run multiple times.
## Troubleshooting
### Firewall blocks my connection
If you're locked out:
- Ensure you can access via Tailscale VPN first
- SSH access (port 22) is always allowed
- The gateway is **only** accessible via Tailscale by design
### Service won't start
```bash
# Check logs
sudo journalctl -u moltbot -n 100
# Verify permissions
sudo ls -la /opt/moltbot
# Test manual start
sudo -i -u moltbot
cd ~/moltbot
pnpm start
```
### Docker sandbox issues
```bash
# Verify Docker is running
sudo systemctl status docker
# Check sandbox image
sudo docker images | grep moltbot-sandbox
# Build sandbox image if missing
cd /opt/moltbot/moltbot
sudo -u moltbot ./scripts/sandbox-setup.sh
```
### Provider login fails
Make sure you're running as the `moltbot` user:
```bash
sudo -i -u moltbot
moltbot channels login
```
## Advanced Configuration
For detailed security architecture and troubleshooting:
- [Security Architecture](https://github.com/moltbot/moltbot-ansible/blob/main/docs/security.md)
- [Technical Details](https://github.com/moltbot/moltbot-ansible/blob/main/docs/architecture.md)
- [Troubleshooting Guide](https://github.com/moltbot/moltbot-ansible/blob/main/docs/troubleshooting.md)
## Related
- [moltbot-ansible](https://github.com/moltbot/moltbot-ansible) — full deployment guide
- [Docker](/install/docker) — containerized gateway setup
- [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation

58
docker-compose/ez-assistant/docs/install/bun.md Normal file
View File

@@ -0,0 +1,58 @@
---
summary: "Bun workflow (experimental): installs and gotchas vs pnpm"
read_when:
- You want the fastest local dev loop (bun + watch)
- You hit Bun install/patch/lifecycle script issues
---
# Bun (experimental)
Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram)
without diverging from pnpm workflows.
⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production.
## Status
- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
- Bun cannot use `pnpm-lock.yaml` and will ignore it.
## Install
Default:
```sh
bun install
```
Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want *no lockfile writes*:
```sh
bun install --no-save
```
## Build / Test (Bun)
```sh
bun run build
bun run vitest run
```
## Bun lifecycle scripts (blocked by default)
Bun may block dependency lifecycle scripts unless explicitly trusted (`bun pm untrusted` / `bun pm trust`).
For this repo, the commonly blocked scripts are not required:
- `@whiskeysockets/baileys` `preinstall`: checks Node major >= 20 (we run Node 22+).
- `protobufjs` `postinstall`: emits warnings about incompatible version schemes (no build artifacts).
If you hit a real runtime issue that requires these scripts, trust them explicitly:
```sh
bun pm trust @whiskeysockets/baileys protobufjs
```
## Caveats
- Some scripts still hardcode pnpm (e.g. `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now.

74
docker-compose/ez-assistant/docs/install/development-channels.md Normal file
View File

@@ -0,0 +1,74 @@
---
summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
read_when:
- You want to switch between stable/beta/dev
- You are tagging or publishing prereleases
---
# Development channels
Last updated: 2026-01-21
Moltbot ships three update channels:
- **stable**: npm dist-tag `latest`.
- **beta**: npm dist-tag `beta` (builds under test).
- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
without changing the version number — dist-tags are the source of truth for npm installs.
## Switching channels
Git checkout:
```bash
moltbot update --channel stable
moltbot update --channel beta
moltbot update --channel dev
```
- `stable`/`beta` check out the latest matching tag (often the same tag).
- `dev` switches to `main` and rebases on the upstream.
npm/pnpm global install:
```bash
moltbot update --channel stable
moltbot update --channel beta
moltbot update --channel dev
```
This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
When you **explicitly** switch channels with `--channel`, Moltbot also aligns
the install method:
- `dev` ensures a git checkout (default `~/moltbot`, override with `CLAWDBOT_GIT_DIR`),
updates it, and installs the global CLI from that checkout.
- `stable`/`beta` installs from npm using the matching dist-tag.
Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
## Plugins and channels
When you switch channels with `moltbot update`, Moltbot also syncs plugin sources:
- `dev` prefers bundled plugins from the git checkout.
- `stable` and `beta` restore npm-installed plugin packages.
## Tagging best practices
- Tag releases you want git checkouts to land on (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
- Keep tags immutable: never move or reuse a tag.
- npm dist-tags remain the source of truth for npm installs:
- `latest` → stable
- `beta` → candidate build
- `dev` → main snapshot (optional)
## macOS app availability
Beta and dev builds may **not** include a macOS app release. That’s OK:
- The git tag and npm dist-tag can still be published.
- Call out “no macOS build for this beta” in release notes or changelog.

447
docker-compose/ez-assistant/docs/install/docker.md Normal file
View File

@@ -0,0 +1,447 @@
---
summary: "Optional Docker-based setup and onboarding for Moltbot"
read_when:
- You want a containerized gateway instead of local installs
- You are validating the Docker flow
---
# Docker (optional)
Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.
## Is Docker right for me?
- **Yes**: you want an isolated, throwaway gateway environment or to run Moltbot on a host without local installs.
- **No**: you’re running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
- **Sandboxing note**: agent sandboxing uses Docker too, but it does **not** require the full gateway to run in Docker. See [Sandboxing](/gateway/sandboxing).
This guide covers:
- Containerized Gateway (full Moltbot in Docker)
- Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)
Sandboxing details: [Sandboxing](/gateway/sandboxing)
## Requirements
- Docker Desktop (or Docker Engine) + Docker Compose v2
- Enough disk for images + logs
## Containerized Gateway (Docker Compose)
### Quick start (recommended)
From repo root:
```bash
./docker-setup.sh
```
This script:
- builds the gateway image
- runs the onboarding wizard
- prints optional provider setup hints
- starts the gateway via Docker Compose
- generates a gateway token and writes it to `.env`
Optional env vars:
- `CLAWDBOT_DOCKER_APT_PACKAGES` — install extra apt packages during build
- `CLAWDBOT_EXTRA_MOUNTS` — add extra host bind mounts
- `CLAWDBOT_HOME_VOLUME` — persist `/home/node` in a named volume
After it finishes:
- Open `http://127.0.0.1:18789/` in your browser.
- Paste the token into the Control UI (Settings → token).
It writes config/workspace on the host:
- `~/.clawdbot/`
- `~/clawd`
Running on a VPS? See [Hetzner (Docker VPS)](/platforms/hetzner).
### Manual flow (compose)
```bash
docker build -t moltbot:local -f Dockerfile .
docker compose run --rm moltbot-cli onboard
docker compose up -d moltbot-gateway
```
### Extra mounts (optional)
If you want to mount additional host directories into the containers, set
`CLAWDBOT_EXTRA_MOUNTS` before running `docker-setup.sh`. This accepts a
comma-separated list of Docker bind mounts and applies them to both
`moltbot-gateway` and `moltbot-cli` by generating `docker-compose.extra.yml`.
Example:
```bash
export CLAWDBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
```
Notes:
- Paths must be shared with Docker Desktop on macOS/Windows.
- If you edit `CLAWDBOT_EXTRA_MOUNTS`, rerun `docker-setup.sh` to regenerate the
extra compose file.
- `docker-compose.extra.yml` is generated. Don’t hand-edit it.
### Persist the entire container home (optional)
If you want `/home/node` to persist across container recreation, set a named
volume via `CLAWDBOT_HOME_VOLUME`. This creates a Docker volume and mounts it at
`/home/node`, while keeping the standard config/workspace bind mounts. Use a
named volume here (not a bind path); for bind mounts, use
`CLAWDBOT_EXTRA_MOUNTS`.
Example:
```bash
export CLAWDBOT_HOME_VOLUME="moltbot_home"
./docker-setup.sh
```
You can combine this with extra mounts:
```bash
export CLAWDBOT_HOME_VOLUME="moltbot_home"
export CLAWDBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh
```
Notes:
- If you change `CLAWDBOT_HOME_VOLUME`, rerun `docker-setup.sh` to regenerate the
extra compose file.
- The named volume persists until removed with `docker volume rm <name>`.
### Install extra apt packages (optional)
If you need system packages inside the image (for example, build tools or media
libraries), set `CLAWDBOT_DOCKER_APT_PACKAGES` before running `docker-setup.sh`.
This installs the packages during the image build, so they persist even if the
container is deleted.
Example:
```bash
export CLAWDBOT_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh
```
Notes:
- This accepts a space-separated list of apt package names.
- If you change `CLAWDBOT_DOCKER_APT_PACKAGES`, rerun `docker-setup.sh` to rebuild
the image.
### Faster rebuilds (recommended)
To speed up rebuilds, order your Dockerfile so dependency layers are cached.
This avoids re-running `pnpm install` unless lockfiles change:
```dockerfile
FROM node:22-bookworm
# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]
```
### Channel setup (optional)
Use the CLI container to configure channels, then restart the gateway if needed.
WhatsApp (QR):
```bash
docker compose run --rm moltbot-cli channels login
```
Telegram (bot token):
```bash
docker compose run --rm moltbot-cli channels add --channel telegram --token "<token>"
```
Discord (bot token):
```bash
docker compose run --rm moltbot-cli channels add --channel discord --token "<token>"
```
Docs: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord)
### Health check
```bash
docker compose exec moltbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"
```
### E2E smoke test (Docker)
```bash
scripts/e2e/onboard-docker.sh
```
### QR import smoke test (Docker)
```bash
pnpm test:docker:qr
```
### Notes
- Gateway bind defaults to `lan` for container use.
- The gateway container is the source of truth for sessions (`~/.clawdbot/agents/<agentId>/sessions/`).
## Agent Sandbox (host gateway + Docker tools)
Deep dive: [Sandboxing](/gateway/sandboxing)
### What it does
When `agents.defaults.sandbox` is enabled, **non-main sessions** run tools inside a Docker
container. The gateway stays on your host, but the tool execution is isolated:
- scope: `"agent"` by default (one container + workspace per agent)
- scope: `"session"` for per-session isolation
- per-scope workspace folder mounted at `/workspace`
- optional agent workspace access (`agents.defaults.sandbox.workspaceAccess`)
- allow/deny tool policy (deny wins)
- inbound media is copied into the active sandbox workspace (`media/inbound/*`) so tools can read it (with `workspaceAccess: "rw"`, this lands in the agent workspace)
Warning: `scope: "shared"` disables cross-session isolation. All sessions share
one container and one workspace.
### Per-agent sandbox profiles (multi-agent)
If you use multi-agent routing, each agent can override sandbox + tool settings:
`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools`). This lets you run
mixed access levels in one gateway:
- Full access (personal agent)
- Read-only tools + read-only workspace (family/work agent)
- No filesystem/shell tools (public agent)
See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples,
precedence, and troubleshooting.
### Default behavior
- Image: `moltbot-sandbox:bookworm-slim`
- One container per agent
- Agent workspace access: `workspaceAccess: "none"` (default) uses `~/.clawdbot/sandboxes`
- `"ro"` keeps the sandbox workspace at `/workspace` and mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`)
- `"rw"` mounts the agent workspace read/write at `/workspace`
- Auto-prune: idle > 24h OR age > 7d
- Network: `none` by default (explicitly opt-in if you need egress)
- Default allow: `exec`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
- Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`
### Enable sandboxing
If you plan to install packages in `setupCommand`, note:
- Default `docker.network` is `"none"` (no egress).
- `readOnlyRoot: true` blocks package installs.
- `user` must be root for `apt-get` (omit `user` or set `user: "0:0"`).
Moltbot auto-recreates containers when `setupCommand` (or docker config) changes
unless the container was **recently used** (within ~5 minutes). Hot containers
log a warning with the exact `moltbot sandbox recreate ...` command.
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared (agent is default)
workspaceAccess: "none", // none | ro | rw
workspaceRoot: "~/.clawdbot/sandboxes",
docker: {
image: "moltbot-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "moltbot-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"]
},
prune: {
idleHours: 24, // 0 disables idle pruning
maxAgeDays: 7 // 0 disables max-age pruning
}
}
}
},
tools: {
sandbox: {
tools: {
allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
}
}
}
}
```
Hardening knobs live under `agents.defaults.sandbox.docker`:
`network`, `user`, `pidsLimit`, `memory`, `memorySwap`, `cpus`, `ulimits`,
`seccompProfile`, `apparmorProfile`, `dns`, `extraHosts`.
Multi-agent: override `agents.defaults.sandbox.{docker,browser,prune}.*` per agent via `agents.list[].sandbox.{docker,browser,prune}.*`
(ignored when `agents.defaults.sandbox.scope` / `agents.list[].sandbox.scope` is `"shared"`).
### Build the default sandbox image
```bash
scripts/sandbox-setup.sh
```
This builds `moltbot-sandbox:bookworm-slim` using `Dockerfile.sandbox`.
### Sandbox common image (optional)
If you want a sandbox image with common build tooling (Node, Go, Rust, etc.), build the common image:
```bash
scripts/sandbox-common-setup.sh
```
This builds `moltbot-sandbox-common:bookworm-slim`. To use it:
```json5
{
agents: { defaults: { sandbox: { docker: { image: "moltbot-sandbox-common:bookworm-slim" } } } }
}
```
### Sandbox browser image
To run the browser tool inside the sandbox, build the browser image:
```bash
scripts/sandbox-browser-setup.sh
```
This builds `moltbot-sandbox-browser:bookworm-slim` using
`Dockerfile.sandbox-browser`. The container runs Chromium with CDP enabled and
an optional noVNC observer (headful via Xvfb).
Notes:
- Headful (Xvfb) reduces bot blocking vs headless.
- Headless can still be used by setting `agents.defaults.sandbox.browser.headless=true`.
- No full desktop environment (GNOME) is needed; Xvfb provides the display.
Use config:
```json5
{
agents: {
defaults: {
sandbox: {
browser: { enabled: true }
}
}
}
}
```
Custom browser image:
```json5
{
agents: {
defaults: {
sandbox: { browser: { image: "my-moltbot-browser" } }
}
}
}
```
When enabled, the agent receives:
- a sandbox browser control URL (for the `browser` tool)
- a noVNC URL (if enabled and headless=false)
Remember: if you use an allowlist for tools, add `browser` (and remove it from
deny) or the tool remains blocked.
Prune rules (`agents.defaults.sandbox.prune`) apply to browser containers too.
### Custom sandbox image
Build your own image and point config to it:
```bash
docker build -t my-moltbot-sbx -f Dockerfile.sandbox .
```
```json5
{
agents: {
defaults: {
sandbox: { docker: { image: "my-moltbot-sbx" } }
}
}
}
```
### Tool policy (allow/deny)
- `deny` wins over `allow`.
- If `allow` is empty: all tools (except deny) are available.
- If `allow` is non-empty: only tools in `allow` are available (minus deny).
### Pruning strategy
Two knobs:
- `prune.idleHours`: remove containers not used in X hours (0 = disable)
- `prune.maxAgeDays`: remove containers older than X days (0 = disable)
Example:
- Keep busy sessions but cap lifetime:
`idleHours: 24`, `maxAgeDays: 7`
- Never prune:
`idleHours: 0`, `maxAgeDays: 0`
### Security notes
- Hard wall only applies to **tools** (exec/read/write/edit/apply_patch).
- Host-only tools like browser/camera/canvas are blocked by default.
- Allowing `browser` in sandbox **breaks isolation** (browser runs on host).
## Troubleshooting
- Image missing: build with [`scripts/sandbox-setup.sh`](https://github.com/moltbot/moltbot/blob/main/scripts/sandbox-setup.sh) or set `agents.defaults.sandbox.docker.image`.
- Container not running: it will auto-create per session on demand.
- Permission errors in sandbox: set `docker.user` to a UID:GID that matches your
mounted workspace ownership (or chown the workspace folder).
- Custom tools not found: Moltbot runs commands with `sh -lc` (login shell), which
sources `/etc/profile` and may reset PATH. Set `docker.env.PATH` to prepend your
custom tool paths (e.g., `/custom/bin:/usr/local/share/npm-global/bin`), or add
a script under `/etc/profile.d/` in your Dockerfile.

181
docker-compose/ez-assistant/docs/install/index.md Normal file
View File

@@ -0,0 +1,181 @@
---
summary: "Install Moltbot (recommended installer, global install, or from source)"
read_when:
- Installing Moltbot
- You want to install from GitHub
---
# Install
Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
## Quick install (recommended)
```bash
curl -fsSL https://molt.bot/install.sh | bash
```
Windows (PowerShell):
```powershell
iwr -useb https://molt.bot/install.ps1 | iex
```
Next step (if you skipped onboarding):
```bash
moltbot onboard --install-daemon
```
## System requirements
- **Node >=22**
- macOS, Linux, or Windows via WSL2
- `pnpm` only if you build from source
## Choose your install path
### 1) Installer script (recommended)
Installs `moltbot` globally via npm and runs onboarding.
```bash
curl -fsSL https://molt.bot/install.sh | bash
```
Installer flags:
```bash
curl -fsSL https://molt.bot/install.sh | bash -s -- --help
```
Details: [Installer internals](/install/installer).
Non-interactive (skip onboarding):
```bash
curl -fsSL https://molt.bot/install.sh | bash -s -- --no-onboard
```
### 2) Global install (manual)
If you already have Node:
```bash
npm install -g moltbot@latest
```
If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g moltbot@latest
```
If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
Or:
```bash
pnpm add -g moltbot@latest
```
Then:
```bash
moltbot onboard --install-daemon
```
### 3) From source (contributors/dev)
```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
```
Tip: if you don’t have a global install yet, run repo commands via `pnpm moltbot ...`.
### 4) Other install options
- Docker: [Docker](/install/docker)
- Nix: [Nix](/install/nix)
- Ansible: [Ansible](/install/ansible)
- Bun (CLI only): [Bun](/install/bun)
## After install
- Run onboarding: `moltbot onboard --install-daemon`
- Quick check: `moltbot doctor`
- Check gateway health: `moltbot status` + `moltbot health`
- Open the dashboard: `moltbot dashboard`
## Install method: npm vs git (installer)
The installer supports two methods:
- `npm` (default): `npm install -g moltbot@latest`
- `git`: clone/build from GitHub and run from a source checkout
### CLI flags
```bash
# Explicit npm
curl -fsSL https://molt.bot/install.sh | bash -s -- --install-method npm
# Install from GitHub (source checkout)
curl -fsSL https://molt.bot/install.sh | bash -s -- --install-method git
```
Common flags:
- `--install-method npm|git`
- `--git-dir <path>` (default: `~/moltbot`)
- `--no-git-update` (skip `git pull` when using an existing checkout)
- `--no-prompt` (disable prompts; required in CI/automation)
- `--dry-run` (print what would happen; make no changes)
- `--no-onboard` (skip onboarding)
### Environment variables
Equivalent env vars (useful for automation):
- `CLAWDBOT_INSTALL_METHOD=git|npm`
- `CLAWDBOT_GIT_DIR=...`
- `CLAWDBOT_GIT_UPDATE=0|1`
- `CLAWDBOT_NO_PROMPT=1`
- `CLAWDBOT_DRY_RUN=1`
- `CLAWDBOT_NO_ONBOARD=1`
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
## Troubleshooting: `moltbot` not found (PATH)
Quick diagnosis:
```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```
If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `moltbot`).
Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.bashrc`):
```bash
# macOS / Linux
export PATH="$(npm prefix -g)/bin:$PATH"
```
On Windows, add the output of `npm prefix -g` to your PATH.
Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
## Update / uninstall
- Updates: [Updating](/install/updating)
- Migrate to a new machine: [Migrating](/install/migrating)
- Uninstall: [Uninstall](/install/uninstall)

122
docker-compose/ez-assistant/docs/install/installer.md Normal file
View File

@@ -0,0 +1,122 @@
---
summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
read_when:
- You want to understand `molt.bot/install.sh`
- You want to automate installs (CI / headless)
- You want to install from a GitHub checkout
---
# Installer internals
Moltbot ships two installer scripts (served from `molt.bot`):
- `https://molt.bot/install.sh` — “recommended” installer (global npm install by default; can also install from a GitHub checkout)
- `https://molt.bot/install-cli.sh` — non-root-friendly CLI installer (installs into a prefix with its own Node)
- `https://molt.bot/install.ps1` — Windows PowerShell installer (npm by default; optional git install)
To see the current flags/behavior, run:
```bash
curl -fsSL https://molt.bot/install.sh | bash -s -- --help
```
Windows (PowerShell) help:
```powershell
& ([scriptblock]::Create((iwr -useb https://molt.bot/install.ps1))) -?
```
If the installer completes but `moltbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
## install.sh (recommended)
What it does (high level):
- Detect OS (macOS / Linux / WSL).
- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
- Choose install method:
- `npm` (default): `npm install -g moltbot@latest`
- `git`: clone/build a source checkout and install a wrapper script
- On Linux: avoid global npm permission errors by switching npm’s prefix to `~/.npm-global` when needed.
- If upgrading an existing install: runs `moltbot doctor --non-interactive` (best effort).
- For git installs: runs `moltbot doctor --non-interactive` after install/update (best effort).
- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
If you *want* `sharp` to link against a globally-installed libvips (or you’re debugging), set:
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://molt.bot/install.sh | bash
```
### Discoverability / “git install” prompt
If you run the installer while **already inside a Moltbot source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
- update and use this checkout (`git`)
- or migrate to the global npm install (`npm`)
In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `CLAWDBOT_INSTALL_METHOD`), otherwise the script exits with code `2`.
### Why Git is needed
Git is required for the `--install-method git` path (clone / pull).
For `npm` installs, Git is *usually* not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
### Why npm hits `EACCES` on fresh Linux
On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm’s global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
`install.sh` mitigates this by switching the prefix to:
- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
## install-cli.sh (non-root CLI installer)
This script installs `moltbot` into a prefix (default: `~/.clawdbot`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don’t want to touch the system Node/npm.
Help:
```bash
curl -fsSL https://molt.bot/install-cli.sh | bash -s -- --help
```
## install.ps1 (Windows PowerShell)
What it does (high level):
- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
- Choose install method:
- `npm` (default): `npm install -g moltbot@latest`
- `git`: clone/build a source checkout and install a wrapper script
- Runs `moltbot doctor --non-interactive` on upgrades and git installs (best effort).
Examples:
```powershell
iwr -useb https://molt.bot/install.ps1 | iex
```
```powershell
iwr -useb https://molt.bot/install.ps1 | iex -InstallMethod git
```
```powershell
iwr -useb https://molt.bot/install.ps1 | iex -InstallMethod git -GitDir "C:\\moltbot"
```
Environment variables:
- `CLAWDBOT_INSTALL_METHOD=git|npm`
- `CLAWDBOT_GIT_DIR=...`
Git requirement:
If you choose `-InstallMethod git` and Git is missing, the installer will print the
Git for Windows link (`https://git-scm.com/download/win`) and exit.
Common Windows issues:
- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
- **"moltbot" is not recognized**: your npm global bin folder is not on PATH. Most systems use
`%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.

190
docker-compose/ez-assistant/docs/install/migrating.md Normal file
View File

@@ -0,0 +1,190 @@
---
summary: "Move (migrate) a Moltbot install from one machine to another"
read_when:
- You are moving Moltbot to a new laptop/server
- You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
---
# Migrating Moltbot to a new machine
This guide migrates a Moltbot Gateway from one machine to another **without redoing onboarding**.
The migration is simple conceptually:
- Copy the **state directory** (`$CLAWDBOT_STATE_DIR`, default: `~/.clawdbot/`) — this includes config, auth, sessions, and channel state.
- Copy your **workspace** (`~/clawd/` by default) — this includes your agent files (memory, prompts, etc.).
But there are common footguns around **profiles**, **permissions**, and **partial copies**.
## Before you start (what you are migrating)
### 1) Identify your state directory
Most installs use the default:
- **State dir:** `~/.clawdbot/`
But it may be different if you use:
- `--profile <name>` (often becomes `~/.clawdbot-<profile>/`)
- `CLAWDBOT_STATE_DIR=/some/path`
If you’re not sure, run on the **old** machine:
```bash
moltbot status
```
Look for mentions of `CLAWDBOT_STATE_DIR` / profile in the output. If you run multiple gateways, repeat for each profile.
### 2) Identify your workspace
Common defaults:
- `~/clawd/` (recommended workspace)
- a custom folder you created
Your workspace is where files like `MEMORY.md`, `USER.md`, and `memory/*.md` live.
### 3) Understand what you will preserve
If you copy **both** the state dir and workspace, you keep:
- Gateway configuration (`moltbot.json`)
- Auth profiles / API keys / OAuth tokens
- Session history + agent state
- Channel state (e.g. WhatsApp login/session)
- Your workspace files (memory, skills notes, etc.)
If you copy **only** the workspace (e.g., via Git), you do **not** preserve:
- sessions
- credentials
- channel logins
Those live under `$CLAWDBOT_STATE_DIR`.
## Migration steps (recommended)
### Step 0 — Make a backup (old machine)
On the **old** machine, stop the gateway first so files aren’t changing mid-copy:
```bash
moltbot gateway stop
```
(Optional but recommended) archive the state dir and workspace:
```bash
# Adjust paths if you use a profile or custom locations
cd ~
tar -czf moltbot-state.tgz .clawdbot
tar -czf clawd-workspace.tgz clawd
```
If you have multiple profiles/state dirs (e.g. `~/.clawdbot-main`, `~/.clawdbot-work`), archive each.
### Step 1 — Install Moltbot on the new machine
On the **new** machine, install the CLI (and Node if needed):
- See: [Install](/install)
At this stage, it’s OK if onboarding creates a fresh `~/.clawdbot/` — you will overwrite it in the next step.
### Step 2 — Copy the state dir + workspace to the new machine
Copy **both**:
- `$CLAWDBOT_STATE_DIR` (default `~/.clawdbot/`)
- your workspace (default `~/clawd/`)
Common approaches:
- `scp` the tarballs and extract
- `rsync -a` over SSH
- external drive
After copying, ensure:
- Hidden directories were included (e.g. `.clawdbot/`)
- File ownership is correct for the user running the gateway
### Step 3 — Run Doctor (migrations + service repair)
On the **new** machine:
```bash
moltbot doctor
```
Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches.
Then:
```bash
moltbot gateway restart
moltbot status
```
## Common footguns (and how to avoid them)
### Footgun: profile / state-dir mismatch
If you ran the old gateway with a profile (or `CLAWDBOT_STATE_DIR`), and the new gateway uses a different one, you’ll see symptoms like:
- config changes not taking effect
- channels missing / logged out
- empty session history
Fix: run the gateway/service using the **same** profile/state dir you migrated, then rerun:
```bash
moltbot doctor
```
### Footgun: copying only `moltbot.json`
`moltbot.json` is not enough. Many providers store state under:
- `$CLAWDBOT_STATE_DIR/credentials/`
- `$CLAWDBOT_STATE_DIR/agents/<agentId>/...`
Always migrate the entire `$CLAWDBOT_STATE_DIR` folder.
### Footgun: permissions / ownership
If you copied as root or changed users, the gateway may fail to read credentials/sessions.
Fix: ensure the state dir + workspace are owned by the user running the gateway.
### Footgun: migrating between remote/local modes
- If your UI (WebUI/TUI) points at a **remote** gateway, the remote host owns the session store + workspace.
- Migrating your laptop won’t move the remote gateway’s state.
If you’re in remote mode, migrate the **gateway host**.
### Footgun: secrets in backups
`$CLAWDBOT_STATE_DIR` contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets:
- store encrypted
- avoid sharing over insecure channels
- rotate keys if you suspect exposure
## Verification checklist
On the new machine, confirm:
- `moltbot status` shows the gateway running
- Your channels are still connected (e.g. WhatsApp doesn’t require re-pair)
- The dashboard opens and shows existing sessions
- Your workspace files (memory, configs) are present
## Related
- [Doctor](/gateway/doctor)
- [Gateway troubleshooting](/gateway/troubleshooting)
- [Where does Moltbot store its data?](/help/faq#where-does-moltbot-store-its-data)

95
docker-compose/ez-assistant/docs/install/nix.md Normal file
View File

@@ -0,0 +1,95 @@
---
summary: "Install Moltbot declaratively with Nix"
read_when:
- You want reproducible, rollback-able installs
- You're already using Nix/NixOS/Home Manager
- You want everything pinned and managed declaratively
---
# Nix Installation
The recommended way to run Moltbot with Nix is via **[nix-moltbot](https://github.com/moltbot/nix-moltbot)** — a batteries-included Home Manager module.
## Quick Start
Paste this to your AI agent (Claude, Cursor, etc.):
```text
I want to set up nix-moltbot on my Mac.
Repository: github:moltbot/nix-moltbot
What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/moltbot-local using templates/agent-first/flake.nix
3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
5. Fill in the template placeholders and run home-manager switch
6. Verify: launchd running, bot responds to messages
Reference the nix-moltbot README for module options.
```
> **📦 Full guide: [github.com/moltbot/nix-moltbot](https://github.com/moltbot/nix-moltbot)**
>
> The nix-moltbot repo is the source of truth for Nix installation. This page is just a quick overview.
## What you get
- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
- Launchd service that survives reboots
- Plugin system with declarative config
- Instant rollback: `home-manager switch --rollback`
---
## Nix Mode Runtime Behavior
When `CLAWDBOT_NIX_MODE=1` is set (automatic with nix-moltbot):
Moltbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
Enable it by exporting:
```bash
CLAWDBOT_NIX_MODE=1
```
On macOS, the GUI app does not automatically inherit shell env vars. You can
also enable Nix mode via defaults:
```bash
defaults write bot.molt.mac moltbot.nixMode -bool true
```
### Config + state paths
Moltbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`.
- `CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`)
- `CLAWDBOT_CONFIG_PATH` (default: `$CLAWDBOT_STATE_DIR/moltbot.json`)
When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
stay out of the immutable store.
### Runtime behavior in Nix mode
- Auto-install and self-mutation flows are disabled
- Missing dependencies surface Nix-specific remediation messages
- UI surfaces a read-only Nix mode banner when present
## Packaging note (macOS)
The macOS packaging flow expects a stable Info.plist template at:
```
apps/macos/Sources/Moltbot/Resources/Info.plist
```
[`scripts/package-mac-app.sh`](https://github.com/moltbot/moltbot/blob/main/scripts/package-mac-app.sh) copies this template into the app bundle and patches dynamic fields
(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
packaging and Nix builds (which do not rely on a full Xcode toolchain).
## Related
- [nix-moltbot](https://github.com/moltbot/nix-moltbot) — full setup guide
- [Wizard](/start/wizard) — non-Nix CLI setup
- [Docker](/install/docker) — containerized setup

78
docker-compose/ez-assistant/docs/install/node.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: "Node.js + npm (PATH sanity)"
summary: "Node.js + npm install sanity: versions, PATH, and global installs"
read_when:
- "You installed Moltbot but `moltbot` is “command not found”"
- "You’re setting up Node.js/npm on a new machine"
- "npm install -g ... fails with permissions or PATH issues"
---
# Node.js + npm (PATH sanity)
Moltbot’s runtime baseline is **Node 22+**.
If you can run `npm install -g moltbot@latest` but later see `moltbot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
## Quick diagnosis
Run:
```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```
If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `moltbot`).
## Fix: put npm’s global bin dir on PATH
1) Find your global npm prefix:
```bash
npm prefix -g
```
2) Add the global npm bin directory to your shell startup file:
- zsh: `~/.zshrc`
- bash: `~/.bashrc`
Example (replace the path with your `npm prefix -g` output):
```bash
# macOS / Linux
export PATH="/path/from/npm/prefix/bin:$PATH"
```
Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
On Windows, add the output of `npm prefix -g` to your PATH.
## Fix: avoid `sudo npm install -g` / permission errors (Linux)
If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
```bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
```
Persist the `export PATH=...` line in your shell startup file.
## Recommended Node install options
You’ll have the fewest surprises if Node/npm are installed in a way that:
- keeps Node updated (22+)
- makes the global npm bin dir stable and on PATH in new shells
Common choices:
- macOS: Homebrew (`brew install node`) or a version manager
- Linux: your preferred version manager, or a distro-supported install that provides Node 22+
- Windows: official Node installer, `winget`, or a Windows Node version manager
If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers.

125
docker-compose/ez-assistant/docs/install/uninstall.md Normal file
View File

@@ -0,0 +1,125 @@
---
summary: "Uninstall Moltbot completely (CLI, service, state, workspace)"
read_when:
- You want to remove Moltbot from a machine
- The gateway service is still running after uninstall
---
# Uninstall
Two paths:
- **Easy path** if `moltbot` is still installed.
- **Manual service removal** if the CLI is gone but the service is still running.
## Easy path (CLI still installed)
Recommended: use the built-in uninstaller:
```bash
moltbot uninstall
```
Non-interactive (automation / npx):
```bash
moltbot uninstall --all --yes --non-interactive
npx -y moltbot uninstall --all --yes --non-interactive
```
Manual steps (same result):
1) Stop the gateway service:
```bash
moltbot gateway stop
```
2) Uninstall the gateway service (launchd/systemd/schtasks):
```bash
moltbot gateway uninstall
```
3) Delete state + config:
```bash
rm -rf "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}"
```
If you set `CLAWDBOT_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
4) Delete your workspace (optional, removes agent files):
```bash
rm -rf ~/clawd
```
5) Remove the CLI install (pick the one you used):
```bash
npm rm -g moltbot
pnpm remove -g moltbot
bun remove -g moltbot
```
6) If you installed the macOS app:
```bash
rm -rf /Applications/Moltbot.app
```
Notes:
- If you used profiles (`--profile` / `CLAWDBOT_PROFILE`), repeat step 3 for each state dir (defaults are `~/.clawdbot-<profile>`).
- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
## Manual service removal (CLI not installed)
Use this if the gateway service keeps running but `moltbot` is missing.
### macOS (launchd)
Default label is `bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.clawdbot.*` may still exist):
```bash
launchctl bootout gui/$UID/bot.molt.gateway
rm -f ~/Library/LaunchAgents/bot.molt.gateway.plist
```
If you used a profile, replace the label and plist name with `bot.molt.<profile>`. Remove any legacy `com.clawdbot.*` plists if present.
### Linux (systemd user unit)
Default unit name is `moltbot-gateway.service` (or `moltbot-gateway-<profile>.service`):
```bash
systemctl --user disable --now moltbot-gateway.service
rm -f ~/.config/systemd/user/moltbot-gateway.service
systemctl --user daemon-reload
```
### Windows (Scheduled Task)
Default task name is `Moltbot Gateway` (or `Moltbot Gateway (<profile>)`).
The task script lives under your state dir.
```powershell
schtasks /Delete /F /TN "Moltbot Gateway"
Remove-Item -Force "$env:USERPROFILE\.clawdbot\gateway.cmd"
```
If you used a profile, delete the matching task name and `~\.clawdbot-<profile>\gateway.cmd`.
## Normal install vs source checkout
### Normal install (install.sh / npm / pnpm / bun)
If you used `https://molt.bot/install.sh` or `install.ps1`, the CLI was installed with `npm install -g moltbot@latest`.
Remove it with `npm rm -g moltbot` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
### Source checkout (git clone)
If you run from a repo checkout (`git clone` + `moltbot ...` / `bun run moltbot ...`):
1) Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
2) Delete the repo directory.
3) Remove state + workspace as shown above.

219
docker-compose/ez-assistant/docs/install/updating.md Normal file
View File

@@ -0,0 +1,219 @@
---
summary: "Updating Moltbot safely (global install or source), plus rollback strategy"
read_when:
- Updating Moltbot
- Something breaks after an update
---
# Updating
Moltbot is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use `moltbot update`, which restarts) → verify.
## Recommended: re-run the website installer (upgrade in place)
The **preferred** update path is to re-run the installer from the website. It
detects existing installs, upgrades in place, and runs `moltbot doctor` when
needed.
```bash
curl -fsSL https://molt.bot/install.sh | bash
```
Notes:
- Add `--no-onboard` if you don’t want the onboarding wizard to run again.
- For **source installs**, use:
```bash
curl -fsSL https://molt.bot/install.sh | bash -s -- --install-method git --no-onboard
```
The installer will `git pull --rebase` **only** if the repo is clean.
- For **global installs**, the script uses `npm install -g moltbot@latest` under the hood.
- Legacy note: `moltbot` remains available as a compatibility shim.
## Before you update
- Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).
- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
- Snapshot your tailoring:
- Config: `~/.clawdbot/moltbot.json`
- Credentials: `~/.clawdbot/credentials/`
- Workspace: `~/clawd`
## Update (global install)
Global install (pick one):
```bash
npm i -g moltbot@latest
```
```bash
pnpm add -g moltbot@latest
```
We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).
To switch update channels (git + npm installs):
```bash
moltbot update --channel beta
moltbot update --channel dev
moltbot update --channel stable
```
Use `--tag <dist-tag|version>` for a one-off install tag/version.
See [Development channels](/install/development-channels) for channel semantics and release notes.
Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.
Then:
```bash
moltbot doctor
moltbot gateway restart
moltbot health
```
Notes:
- If your Gateway runs as a service, `moltbot gateway restart` is preferred over killing PIDs.
- If you’re pinned to a specific version, see “Rollback / pinning” below.
## Update (`moltbot update`)
For **source installs** (git checkout), prefer:
```bash
moltbot update
```
It runs a safe-ish update flow:
- Requires a clean worktree.
- Switches to the selected channel (tag or branch).
- Fetches + rebases against the configured upstream (dev channel).
- Installs deps, builds, builds the Control UI, and runs `moltbot doctor`.
- Restarts the gateway by default (use `--no-restart` to skip).
If you installed via **npm/pnpm** (no git metadata), `moltbot update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.
## Update (Control UI / RPC)
The Control UI has **Update & Restart** (RPC: `update.run`). It:
1) Runs the same source-update flow as `moltbot update` (git checkout only).
2) Writes a restart sentinel with a structured report (stdout/stderr tail).
3) Restarts the gateway and pings the last active session with the report.
If the rebase fails, the gateway aborts and restarts without applying the update.
## Update (from source)
From the repo checkout:
Preferred:
```bash
moltbot update
```
Manual (equivalent-ish):
```bash
git pull
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
moltbot doctor
moltbot health
```
Notes:
- `pnpm build` matters when you run the packaged `moltbot` binary ([`dist/entry.js`](https://github.com/moltbot/moltbot/blob/main/dist/entry.js)) or use Node to run `dist/`.
- If you run from a repo checkout without a global install, use `pnpm moltbot ...` for CLI commands.
- If you run directly from TypeScript (`pnpm moltbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
- Switching between global and git installs is easy: install the other flavor, then run `moltbot doctor` so the gateway service entrypoint is rewritten to the current install.
## Always Run: `moltbot doctor`
Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.
Note: if you’re on a **source install** (git checkout), `moltbot doctor` will offer to run `moltbot update` first.
Typical things it does:
- Migrate deprecated config keys / legacy config file locations.
- Audit DM policies and warn on risky “open” settings.
- Check Gateway health and can offer to restart.
- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Moltbot services.
- On Linux, ensure systemd user lingering (so the Gateway survives logout).
Details: [Doctor](/gateway/doctor)
## Start / stop / restart the Gateway
CLI (works regardless of OS):
```bash
moltbot gateway status
moltbot gateway stop
moltbot gateway restart
moltbot gateway --port 18789
moltbot logs --follow
```
If you’re supervised:
- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/bot.molt.gateway` (use `bot.molt.<profile>`; legacy `com.clawdbot.*` still works)
- Linux systemd user service: `systemctl --user restart moltbot-gateway[-<profile>].service`
- Windows (WSL2): `systemctl --user restart moltbot-gateway[-<profile>].service`
- `launchctl`/`systemctl` only work if the service is installed; otherwise run `moltbot gateway install`.
Runbook + exact service labels: [Gateway runbook](/gateway)
## Rollback / pinning (when something breaks)
### Pin (global install)
Install a known-good version (replace `<version>` with the last working one):
```bash
npm i -g moltbot@<version>
```
```bash
pnpm add -g moltbot@<version>
```
Tip: to see the current published version, run `npm view moltbot version`.
Then restart + re-run doctor:
```bash
moltbot doctor
moltbot gateway restart
```
### Pin (source) by date
Pick a commit from a date (example: “state of main as of 2026-01-01”):
```bash
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
```
Then reinstall deps + restart:
```bash
pnpm install
pnpm build
moltbot gateway restart
```
If you want to go back to latest later:
```bash
git checkout main
git pull
```
## If you’re stuck
- Run `moltbot doctor` again and read the output carefully (it often tells you the fix).
- Check: [Troubleshooting](/gateway/troubleshooting)
- Ask in Discord: https://channels.discord.gg/clawd