Files
2026-11-01 15:52:46 -05:00

157 lines
10 KiB
Markdown

# Installation
## Requirements
- Linux with systemd (`systemd-nspawn`, `systemd-machined`, `systemd-networkd`), running as root. Containers run with user namespacing and ID-mapped mounts, so you need systemd 250 or newer and a kernel that supports ID-mapped mounts for the filesystems holding `/nix/store`, `state_dir` and the drives (btrfs, ext4 and xfs on any recent kernel).
- 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. It has to be a multi-user install with `nix-daemon` running: containers build through `/nix/var/nix/daemon-socket`, and won't start without it. The daemon sees containers as untrusted users (they run as unprivileged host uids), so `trusted-users` needs no changes, but `allowed-users` must still allow everyone (the default `*`). Their builds go into the host's store, so run `nix-collect-garbage` or `nix.gc` now and then.
- 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.
Updating an existing app: paste the new `slack-manifest.yaml` under **App Manifest**, then reinstall the app so new scopes and events (such as the assistant pane or thread replies) take effect. The bot token stays the same.
## 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`, and after upgrading the bot: the container includes `slackerbot-tools` (the agent's `send_file` tool) from the same checkout. 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`, in-flight replies, 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 |
| `max_send_file_mb` | Largest file the agent may send, and the largest attachment copied in (default 100, at most 1024) |
| `[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 6) |
## 4. Secrets
The Slack tokens from step 1 and the model API key are read from the bot's **environment**. Put them in a root-only env file, kept out of git and the Nix store:
```
sudo install -d -m 700 /etc/slackerbot
sudo install -m 600 /dev/null /etc/slackerbot/secrets
sudoedit /etc/slackerbot/secrets
```
```sh
SLACK_APP_TOKEN=xapp-…
SLACK_BOT_TOKEN=xoxb-…
ANTHROPIC_API_KEY=sk-ant-…
CLUSTER_SECRET=…
```
One `NAME=value` per line, with no quotes needed and no comments after a value (systemd would read the comment as part of the value). `CLUSTER_SECRET` is only needed with more than one node.
| Variable | Overrides | Needed on |
| ----------------------------------------------------------- | --------------------------------- | ------------------------ |
| `SLACK_APP_TOKEN` | `[slack] app_token` | master |
| `SLACK_BOT_TOKEN` | `[slack] bot_token` | master |
| `CLUSTER_SECRET` | `[cluster] secret` | every node, if clustered |
| anything named in `[agent_env]` (e.g. `$ANTHROPIC_API_KEY`) | expanded into the container's env | master |
The master refuses to start without both Slack tokens. You _can_ write them into `[slack]` in the config instead, but then the config holds secrets. With NixOS, the config file is copied into the world-readable Nix store, so use the env file there.
The bot writes the `[agent_env]` values, with `$VARS` expanded, to a root-only file under `state_dir/env/`, and bind-mounts it read-only into the container at `/var/lib/slackerbot/agent.env`, where goose reads it at start. To give goose another key, add it to the secrets file and reference it in `[agent_env]`:
```toml
[agent_env]
GOOSE_PROVIDER = "anthropic"
ANTHROPIC_API_KEY = "$ANTHROPIC_API_KEY"
```
## 5. 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"; # from step 4; a string path, so it stays out of the Nix store
};
```
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
```
sudo nix build git+https://gitea.skyg.ca/ari/slacker-bot.git#slackerbot -o /opt/slackerbot # or: cd slackerbot && go build
```
Or build a static binary with Bazel from a checkout: `bazel build --config=release //slackerbot:slackerbot_tar` produces `bazel-bin/slackerbot/slackerbot_tar.tar.gz`, which holds `usr/bin/slackerbot`.
Run it as a systemd service so the secrets file from step 4 is loaded. Save this as `/etc/systemd/system/slackerbot.service`:
```ini
[Unit]
Description=slackerbot
After=network-online.target systemd-machined.service
Wants=network-online.target
[Service]
ExecStart=/opt/slackerbot/bin/slackerbot -mode master -config /etc/slackerbot/config.toml
EnvironmentFile=/etc/slackerbot/secrets
StateDirectory=slackerbot
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
```
sudo systemctl daemon-reload && sudo systemctl enable --now slackerbot
journalctl -u slackerbot -f
```
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`.
## 6. 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, but each needs `CLUSTER_SECRET` in its own secrets file (step 4).
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**.
- **In-flight replies** are in `state_dir/in-flight-<channel>.json`, one file per channel while it has a reply in progress. The bot picks them back up when it starts. To stop a reply from being resumed, stop the bot and delete its entry (or the file).
- **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.