This commit is contained in:
ari committed 2026-11-01 13:13:04 -05:00
1 parent 0ac61b4ece
commit 7a8fa22e70
7 files changed
+386 -237

No files matched your search

+94
View File
@@ -0,0 +1,94 @@
# Installation
## Requirements
- Linux with systemd (`systemd-nspawn`, `systemd-machined`, `systemd-networkd`), running as root.
- One or more **btrfs** folders for home folders. Quotas are switched on automatically.
- Nix with flakes, to build the bot and the container system. NixOS is easiest, but not required.
- An API key for the model goose should use (e.g. Anthropic).
## 1. Slack app
1. Go to <https://api.slack.com/apps> → **Create New App** → **From a manifest**, and paste `slack-manifest.yaml`.
2. Install it to your workspace and copy the **bot token** (`xoxb-…`).
3. Under **Basic Information → App-Level Tokens**, create a token with the `connections:write` scope (`xapp-…`).
The app uses Socket Mode, so the bot needs no public URL.
## 2. Container system
Build the NixOS system each container boots:
```
nix build git+https://gitea.skyg.ca/ari/slacker-bot.git#agent -o /var/lib/slackerbot/agent-system
# or, from a checkout:
nix build .#agent -o /var/lib/slackerbot/agent-system
```
Rebuild the same way after changing `nix/container.nix`. Each container picks up the new build on its next start. `nix/container.nix` runs `goose serve`, which needs a recent goose. If nixpkgs' `goose-cli` is too old, override it there.
## 3. Config
Copy `config.example.toml` and edit it. The important parts:
| Setting | What |
|---|---|
| `system` | The build from step 2, e.g. `/var/lib/slackerbot/agent-system` |
| `state_dir` | Where `state.json`, env files and cluster certificates live |
| `[agent_env]` | Environment for goose (provider, model, API key). `$VARS` are expanded from the bot's environment |
| `[container]`, `[max_container]` | Default and largest container size |
| `[host_reserve]` | RAM/CPU kept free for the host |
| `idle_timeout`, `max_idle_timeout`, `allow_indefinite` | Idle shutdown rules |
| `[storage]` | Default guaranteed (`min`) and cap (`max`) home size, and the largest cap anyone may set (`limit`) |
| `[[drives]]` | btrfs folders for home folders, each with a `reserve` kept free |
| `[permissions]` | Starting permissions, copied in on first start only (see USERGUIDE.md) |
| `[cluster]` | Only for more than one node (see step 5) |
Secrets go in the environment rather than the file: `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, `CLUSTER_SECRET`, and any API keys used in `[agent_env]`.
## 4. Run the bot
### NixOS
Add the flake to your system flake and import the host module:
```nix
inputs.slackerbot.url = "git+https://gitea.skyg.ca/ari/slacker-bot.git";
# in your host's modules:
imports = [ inputs.slackerbot.nixosModules.host ];
services.slackerbot = {
enable = true;
configFile = ./slackerbot.toml;
environmentFile = "/etc/slackerbot/secrets"; # SLACK_APP_TOKEN=…, SLACK_BOT_TOKEN=…, ANTHROPIC_API_KEY=…
};
```
The module runs the bot as a systemd service with `/var/lib/slackerbot` as its state directory. It also sets up `systemd-networkd` to give each container's `ve-*` link an address over DHCP with NAT, and trusts those links in the firewall.
### Other Linux
```
nix build git+https://gitea.skyg.ca/ari/slacker-bot.git#slackerbot # or: cd slackerbot && go build
sudo slackerbot -config /etc/slackerbot/config.toml
```
Make sure `systemd-networkd` manages `ve-*` links. systemd ships `80-container-ve.network` for this. `btrfs-progs` must be on the bot's `PATH`.
Check the log for the node's capacity line and "connected to Slack", then DM the bot `help`.
## 5. More nodes (optional)
1. On every node, set the same `[cluster] secret` (16+ characters), plus its own `system`, `[[drives]]` and `host_reserve`, and build the container system there. Slaves don't need Slack tokens or `agent_env`, because the master sends those.
2. **Master:** set `cluster.listen = ":7946"` and open the port. On NixOS: `services.slackerbot.clusterPort = 7946`.
3. **Slaves:** set `cluster.master = "wss://<master>:7946"` and a unique `cluster.name` (default: the hostname). Run with `-mode slave`. On NixOS: `services.slackerbot.mode = "slave"`.
4. The master logs its certificate fingerprint at startup. Put it in each slave's `cluster.master_fingerprint`. If you leave it empty, a slave trusts the first certificate it sees, saves it in `state_dir/master.fingerprint`, and refuses any other from then on.
`nodes` in Slack should now list every node.
## Maintenance
- **Permissions** live in the master's `state.json` after the first start, and editing the config doesn't change them. To start over from the config, stop the master and delete the `permissions` entry from `state.json`.
- **Deleting a home folder for good:** stop its container, run `btrfs subvolume delete <drive path>/<u-… or c-…>`, then, with the bot stopped, remove its owner from `state.json`. Nothing deletes homes automatically, so their guaranteed space stays taken. This includes homes left on a dead slave after **Create new container**.
- **Upgrading** the bot doesn't stop running containers, because each runs in its own `slackerbot-<machine>.service` unit.
- Find user and channel IDs in Slack with **Copy member ID** on a profile, or at the bottom of a channel's **About** tab.