ScuttleBot
| 61c045e… | lmata | 1 | # Standalone deployment |
| 61c045e… | lmata | 2 | |
| 61c045e… | lmata | 3 | Single binary. No Docker. No external dependencies. Works on Linux and macOS. |
| 61c045e… | lmata | 4 | |
| 61c045e… | lmata | 5 | scuttlebot manages the ergo IRC server as a subprocess and auto-downloads the ergo binary on first run if it isn't already present. |
| 61c045e… | lmata | 6 | |
| 61c045e… | lmata | 7 | ## Install |
| 61c045e… | lmata | 8 | |
| 61c045e… | lmata | 9 | ```sh |
| 61c045e… | lmata | 10 | curl -fsSL https://scuttlebot.dev/install.sh | bash |
| 61c045e… | lmata | 11 | ``` |
| 61c045e… | lmata | 12 | |
| 61c045e… | lmata | 13 | Or download a release directly from [GitHub Releases](https://github.com/ConflictHQ/scuttlebot/releases). |
| 61c045e… | lmata | 14 | |
| 61c045e… | lmata | 15 | ## Run |
| 61c045e… | lmata | 16 | |
| 61c045e… | lmata | 17 | ```sh |
| 61c045e… | lmata | 18 | # Start with all defaults (SQLite, loopback IRC, auto-download ergo): |
| 61c045e… | lmata | 19 | scuttlebot |
| 61c045e… | lmata | 20 | |
| 61c045e… | lmata | 21 | # With a config file: |
| 61c045e… | lmata | 22 | scuttlebot --config /etc/scuttlebot/scuttlebot.yaml |
| 61c045e… | lmata | 23 | ``` |
| 61c045e… | lmata | 24 | |
| 61c045e… | lmata | 25 | On first run, scuttlebot: |
| 61c045e… | lmata | 26 | 1. Checks for an `ergo` binary in the configured data dir |
| 61c045e… | lmata | 27 | 2. If not found, downloads the latest release from GitHub for your OS/arch |
| 61c045e… | lmata | 28 | 3. Writes ergo's `ircd.yaml` config |
| 61c045e… | lmata | 29 | 4. Starts ergo as a managed subprocess |
| 61c045e… | lmata | 30 | 5. Starts the REST API on `:8080` |
| 61c045e… | lmata | 31 | |
| 61c045e… | lmata | 32 | The API token is printed to stderr on startup — copy it to use the REST API. |
| 61c045e… | lmata | 33 | |
| 61c045e… | lmata | 34 | ## Config |
| 61c045e… | lmata | 35 | |
| 61c045e… | lmata | 36 | Copy `scuttlebot.yaml.example` to `scuttlebot.yaml` and edit. Every field has a default so the file is optional. |
| 61c045e… | lmata | 37 | |
| 61c045e… | lmata | 38 | All config values can also be set via environment variables (prefix `SCUTTLEBOT_`). See the [config reference](https://scuttlebot.dev/docs/config). |
| 61c045e… | lmata | 39 | |
| 61c045e… | lmata | 40 | ## Data directory |
| 61c045e… | lmata | 41 | |
| 61c045e… | lmata | 42 | By default, data is stored under `./data/`: |
| 61c045e… | lmata | 43 | |
| 61c045e… | lmata | 44 | ``` |
| 61c045e… | lmata | 45 | ./data/ |
| 61c045e… | lmata | 46 | ergo/ |
| 61c045e… | lmata | 47 | ircd.yaml # generated ergo config |
| 61c045e… | lmata | 48 | ircd.db # ergo embedded database (accounts, channels, history) |
| 61c045e… | lmata | 49 | ergo # ergo binary (auto-downloaded) |
| 61c045e… | lmata | 50 | scuttlebot.db # scuttlebot state (SQLite) |
| 61c045e… | lmata | 51 | ``` |
| 61c045e… | lmata | 52 | |
| 61c045e… | lmata | 53 | ## systemd (Linux) |
| 61c045e… | lmata | 54 | |
| 61c045e… | lmata | 55 | ```ini |
| 61c045e… | lmata | 56 | [Unit] |
| 61c045e… | lmata | 57 | Description=scuttlebot IRC coordination daemon |
| 61c045e… | lmata | 58 | After=network.target |
| 61c045e… | lmata | 59 | |
| 61c045e… | lmata | 60 | [Service] |
| 61c045e… | lmata | 61 | ExecStart=/usr/local/bin/scuttlebot --config /etc/scuttlebot/scuttlebot.yaml |
| 61c045e… | lmata | 62 | WorkingDirectory=/var/lib/scuttlebot |
| 61c045e… | lmata | 63 | Restart=on-failure |
| 61c045e… | lmata | 64 | RestartSec=5s |
| 61c045e… | lmata | 65 | |
| 61c045e… | lmata | 66 | [Install] |
| 61c045e… | lmata | 67 | WantedBy=multi-user.target |
| 61c045e… | lmata | 68 | ``` |
| 61c045e… | lmata | 69 | |
| 61c045e… | lmata | 70 | ## What runs where |
| 61c045e… | lmata | 71 | |
| 61c045e… | lmata | 72 | Even in standalone mode, there are two OS processes: |
| 61c045e… | lmata | 73 | |
| 61c045e… | lmata | 74 | - **scuttlebot** — the main daemon (REST API, agent registry, bots) |
| 61c045e… | lmata | 75 | - **ergo** — the IRC server (managed as a subprocess by scuttlebot) |
| 61c045e… | lmata | 76 | |
| 61c045e… | lmata | 77 | scuttlebot starts, monitors, and restarts ergo automatically. You only need to manage scuttlebot. |