# Getting started

Audience: a new operator or contributor who has never run ocbot. Purpose: get from a clean machine to a verified running bot. Prerequisites: Linux is the supported host (the production units are systemd); the bot is built for a single operator — you need a chat surface to talk on (Discord, Signal, or both) and a host you control.

# Prerequisites

# Step 1 — Create the Discord bot

1. Create an application in the Discord developer portal↗ .
2. Open the Bot tab, reset the token, and copy it — this is DISCORD_TOKEN.
3. Enable the Message Content privileged intent. The bot needs it to map replies to inbox reports back to sessions.
4. Under OAuth2 → URL generator, select the scopes bot and applications.commands, and at minimum the permissions Send Messages, Attach Files, and Add Reactions. Open the generated URL to invite the bot to a private server you own.
5. In Discord, enable Developer Mode (user settings → Appearance), right-click your own name, and Copy User ID — this is ALLOWED_USER_ID.

# Step 2 — Start the opencode server

ocbot expects the server on loopback with a password. The minimal manual start:

OPENCODE_PASSWORD="<choose a password>" opencode serve --hostname 127.0.0.1 --port 8080

Check it answers:

curl -su "opencode:$OPENCODE_PASSWORD" http://127.0.0.1:8080/api/info

For production, use the provided unit instead: DEPLOYMENT .

# Step 3 — Build

From the repository root ([TODO: repo URL] — clone it first):

cargo build --release

The binary lands at target/release/ocbot.

# Step 4 — Configure

ocbot reads config/config.toml relative to the directory you run it from, or the path in OCBOT_CONFIG. Unknown keys are a load error — start from the example:

cp config/config.toml.example config/config.toml
$EDITOR config/config.toml

You must set opencode_url, and every key of every surface you select. Everything else has a default.

# Surfaces

channel selects which chat surfaces run — one name or a list:

channel = ["discord", "signal"]

A [signal] section you are not using yet is fine — it is a warning, not an error, so you can stage the config before the daemon exists.

Prompt templates live in templates/ (fresh.md for a new run, resume.md for Park & redo). They support exactly four slots: {label}, {plan_path}, {git_log}, {git_status}; an unknown slot is a load-time error.

# Step 5 — Set the secrets

Secrets come from the environment, never the config file.

For development:

export DISCORD_TOKEN="<bot token>"
export OPENCODE_PASSWORD="<opencode password>"
export ALLOWED_USER_ID="<your Discord user id>"
# and, on the Signal surface:
export SIGNAL_OPERATOR="+15559876543"

In production these live in /etc/ocbot/ocbot.env, mode 0600 — see DEPLOYMENT .

# Step 6 — Run and verify

Run from the repository root (config, templates, and the database resolve relative to it):

cargo run --release

The startup doctor fails fast — with a named reason — on a bad config, missing secrets, a non-v2 server, an unhealthy signal-cli daemon (Signal surface only), or a permissions baseline missing its ask patterns. A healthy boot shows JSON log lines and a connected to discord line — plus signal-cli daemon healthy when the Signal surface runs.

Then verify on each surface you selected:

1. Discord: send /status in a DM with the bot. You should see server reachability and version, no active actions, no held locks.

2. Signal: send status from your phone; the same answer arrives as a plain message.

3. Check the metrics endpoint:

   curl -s http://127.0.0.1:9464/metrics | grep ocbot_surface_up

   1 for every surface you selected.

4. Start a real run in a scratch repository with /run (Discord) or run <dir> (Signal), and make a decision on the report.

# Degraded mode

If the opencode server is unreachable at boot, the bot starts anyway in degraded mode and recovers on its own when the server returns. You get exactly one “server down” post and one recovery post — no spam (FR-38). With [events] enabled = false, the bot runs the pure polling architecture: every fallback tick uses its configured interval, and no SSE connection is made.

# Signal commands

Send plain text to the bot’s number; it answers with plain messages.

Messages that carry decision buttons also render a legend (✅ accept · 🔁 follow up · 🅿️ park · 🗑️ discard, keycaps for gate options): react with the emoji to decide. Ten minutes of silence closes an open flow; cancel closes it now.

# Discord commands

Beyond slash commands: report messages carry decision buttons (Accept, Follow up, Park & redo, or Discard, depending on the outcome); gates carry Once / Always / Reject (or form buttons and a modal); replying to an inbox report adopts that session; attaching a file in the DM saves it under inbox_dir and offers its path to the agent. Reactions on the origin message are the quiet status light.

# Troubleshooting