docs: reorganize documentation structure
This commit is contained in:
Peter Steinberger
68
docs/install/bun.md
Normal file
68
docs/install/bun.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
summary: "Bun workflow (preferred): installs, patches, and gotchas vs pnpm"
|
||||
read_when:
|
||||
- You want the fastest local dev loop (bun + watch)
|
||||
- You hit Bun install/patch/lifecycle script issues
|
||||
---
|
||||
|
||||
# Bun
|
||||
|
||||
Goal: run this repo with **Bun** (preferred) without losing pnpm patch behavior.
|
||||
|
||||
## Status
|
||||
|
||||
- Bun is the preferred local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
|
||||
- `pnpm` is still 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
|
||||
```
|
||||
|
||||
## pnpm patchedDependencies under Bun
|
||||
|
||||
pnpm supports `package.json#pnpm.patchedDependencies` and records it in `pnpm-lock.yaml`.
|
||||
Bun does not support pnpm patches, so we apply them in `postinstall` when Bun is detected:
|
||||
|
||||
- [`scripts/postinstall.js`](https://github.com/clawdbot/clawdbot/blob/main/scripts/postinstall.js) runs only for Bun installs and applies every entry from `package.json#pnpm.patchedDependencies` into `node_modules/...` using `git apply` (idempotent).
|
||||
|
||||
To add a new patch that works in both pnpm + Bun:
|
||||
|
||||
1. Add an entry to `package.json#pnpm.patchedDependencies`
|
||||
2. Add the patch file under `patches/`
|
||||
3. Run `pnpm install` (updates `pnpm-lock.yaml` patch hash)
|
||||
|
||||
## 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.
|
||||
261
docs/install/docker.md
Normal file
261
docs/install/docker.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
summary: "Optional Docker-based setup and onboarding for Clawdbot"
|
||||
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.
|
||||
|
||||
This guide covers:
|
||||
- Containerized Gateway (full Clawdbot in Docker)
|
||||
- Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)
|
||||
|
||||
## 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
|
||||
- runs WhatsApp login
|
||||
- starts the gateway via Docker Compose
|
||||
|
||||
It writes config/workspace on the host:
|
||||
- `~/.clawdbot/`
|
||||
- `~/clawd`
|
||||
|
||||
### Manual flow (compose)
|
||||
|
||||
```bash
|
||||
docker build -t clawdbot:local -f Dockerfile .
|
||||
docker compose run --rm clawdbot-cli onboard
|
||||
docker compose run --rm clawdbot-cli login
|
||||
docker compose up -d clawdbot-gateway
|
||||
```
|
||||
|
||||
### Health check
|
||||
|
||||
```bash
|
||||
docker compose exec clawdbot-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/`).
|
||||
|
||||
## Per-session Agent Sandbox (host gateway + Docker tools)
|
||||
|
||||
### What it does
|
||||
|
||||
When `agent.sandbox` is enabled, **non-main sessions** run tools inside a Docker
|
||||
container. The gateway stays on your host, but the tool execution is isolated:
|
||||
- one container per session (hard wall)
|
||||
- per-session workspace folder mounted at `/workspace`
|
||||
- allow/deny tool policy (deny wins)
|
||||
- inbound media is copied into the sandbox workspace (`media/inbound/*`) so tools can read it
|
||||
|
||||
Warning: setting `perSession: false` disables per-session isolation. All sessions
|
||||
share one container and one workspace, so there is no cross-session isolation.
|
||||
|
||||
### Default behavior
|
||||
|
||||
- Image: `clawdbot-sandbox:bookworm-slim`
|
||||
- One container per session
|
||||
- Workspace per session under `~/.clawdbot/sandboxes`
|
||||
- Auto-prune: idle > 24h OR age > 7d
|
||||
- Network: `none` by default (explicitly opt-in if you need egress)
|
||||
- Default allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
|
||||
- Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`
|
||||
|
||||
### Enable sandboxing
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
sandbox: {
|
||||
mode: "non-main", // off | non-main | all
|
||||
perSession: true,
|
||||
workspaceRoot: "~/.clawdbot/sandboxes",
|
||||
docker: {
|
||||
image: "clawdbot-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: "clawdbot-sandbox",
|
||||
dns: ["1.1.1.1", "8.8.8.8"],
|
||||
extraHosts: ["internal.service:10.0.0.5"]
|
||||
},
|
||||
tools: {
|
||||
allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
|
||||
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
|
||||
},
|
||||
prune: {
|
||||
idleHours: 24, // 0 disables idle pruning
|
||||
maxAgeDays: 7 // 0 disables max-age pruning
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Hardening knobs live under `agent.sandbox.docker`:
|
||||
`network`, `user`, `pidsLimit`, `memory`, `memorySwap`, `cpus`, `ulimits`,
|
||||
`seccompProfile`, `apparmorProfile`, `dns`, `extraHosts`.
|
||||
|
||||
### Build the default sandbox image
|
||||
|
||||
```bash
|
||||
scripts/sandbox-setup.sh
|
||||
```
|
||||
|
||||
This builds `clawdbot-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 `clawdbot-sandbox-common:bookworm-slim`. To use it:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: { sandbox: { docker: { image: "clawdbot-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 `clawdbot-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 `agent.sandbox.browser.headless=true`.
|
||||
- No full desktop environment (GNOME) is needed; Xvfb provides the display.
|
||||
|
||||
Use config:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
sandbox: {
|
||||
browser: { enabled: true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Custom browser image:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
sandbox: { browser: { image: "my-clawdbot-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 (`agent.sandbox.prune`) apply to browser containers too.
|
||||
|
||||
### Custom sandbox image
|
||||
|
||||
Build your own image and point config to it:
|
||||
|
||||
```bash
|
||||
docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .
|
||||
```
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
sandbox: { docker: { image: "my-clawdbot-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** (bash/read/write/edit).
|
||||
- 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/clawdbot/clawdbot/blob/main/scripts/sandbox-setup.sh) or set `agent.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).
|
||||
95
docs/install/nix.md
Normal file
95
docs/install/nix.md
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
summary: "Install Clawdbot 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 Clawdbot with Nix is via **[nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** — a batteries-included Home Manager module.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Paste this to your AI agent (Claude, Cursor, etc.):
|
||||
|
||||
```text
|
||||
I want to set up nix-clawdbot on my Mac.
|
||||
Repository: github:clawdbot/nix-clawdbot
|
||||
|
||||
What I need you to do:
|
||||
1. Check if Determinate Nix is installed (if not, install it)
|
||||
2. Create a local flake at ~/code/clawdbot-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-clawdbot README for module options.
|
||||
```
|
||||
|
||||
> **📦 Full guide: [github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)**
|
||||
>
|
||||
> The nix-clawdbot 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-clawdbot):
|
||||
|
||||
Clawdbot 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 com.clawdbot.mac clawdbot.nixMode -bool true
|
||||
```
|
||||
|
||||
### Config + state paths
|
||||
|
||||
Clawdbot 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/clawdbot.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/Clawdbot/Resources/Info.plist
|
||||
```
|
||||
|
||||
[`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/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-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
|
||||
- [Wizard](/wizard) — non-Nix CLI setup
|
||||
- [Docker](/docker) — containerized setup
|
||||
138
docs/install/updating.md
Normal file
138
docs/install/updating.md
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
summary: "Updating Clawdbot safely (npm or source), plus rollback strategy"
|
||||
read_when:
|
||||
- Updating Clawdbot
|
||||
- Something breaks after an update
|
||||
---
|
||||
|
||||
# Updating
|
||||
|
||||
Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart → verify.
|
||||
|
||||
## Before you update
|
||||
|
||||
- Know how you installed: **npm** (global) vs **from source** (git clone).
|
||||
- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd/Scheduled Task).
|
||||
- Snapshot your tailoring:
|
||||
- Config: `~/.clawdbot/clawdbot.json`
|
||||
- Credentials: `~/.clawdbot/credentials/`
|
||||
- Workspace: `~/clawd`
|
||||
|
||||
## Update (npm install)
|
||||
|
||||
Global install (pick one):
|
||||
|
||||
```bash
|
||||
npm i -g clawdbot@latest
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g clawdbot@latest
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
clawdbot doctor
|
||||
clawdbot gateway restart
|
||||
clawdbot health
|
||||
```
|
||||
|
||||
Notes:
|
||||
- If your Gateway runs as a service, `clawdbot gateway restart` is preferred over killing PIDs.
|
||||
- If you’re pinned to a specific version, see “Rollback / pinning” below.
|
||||
|
||||
## Update (from source)
|
||||
|
||||
From the repo checkout:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm ui:install
|
||||
pnpm ui:build
|
||||
pnpm clawdbot doctor
|
||||
pnpm clawdbot health
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `pnpm build` matters when you run the packaged `clawdbot` binary ([`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js)) or use Node to run `dist/`.
|
||||
- If you run directly from TypeScript (`pnpm clawdbot ...` / `bun run clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
|
||||
|
||||
## Always run: `clawdbot doctor`
|
||||
|
||||
Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.
|
||||
|
||||
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/schtasks) to current Clawdbot services.
|
||||
- On Linux, ensure systemd user lingering (so the Gateway survives logout).
|
||||
|
||||
Details: [Doctor](/doctor)
|
||||
|
||||
## Start / stop / restart the Gateway
|
||||
|
||||
CLI (works regardless of OS):
|
||||
|
||||
```bash
|
||||
clawdbot gateway stop
|
||||
clawdbot gateway restart
|
||||
clawdbot gateway --port 18789
|
||||
```
|
||||
|
||||
If you’re supervised:
|
||||
- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
|
||||
- Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
|
||||
- Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
|
||||
|
||||
Runbook + exact service labels: [Gateway runbook](/gateway)
|
||||
|
||||
## Rollback / pinning (when something breaks)
|
||||
|
||||
### Pin (npm)
|
||||
|
||||
Install a known-good version:
|
||||
|
||||
```bash
|
||||
npm i -g clawdbot@2026.1.5-3
|
||||
```
|
||||
|
||||
Then restart + re-run doctor:
|
||||
|
||||
```bash
|
||||
clawdbot doctor
|
||||
clawdbot 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
|
||||
clawdbot gateway restart
|
||||
```
|
||||
|
||||
If you want to go back to latest later:
|
||||
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
```
|
||||
|
||||
## If you’re stuck
|
||||
|
||||
- Run `clawdbot doctor` again and read the output carefully (it often tells you the fix).
|
||||
- Check: [Troubleshooting](/troubleshooting)
|
||||
- Ask in Discord: https://discord.gg/clawd
|
||||
Reference in New Issue
Block a user