9.0 KiB
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
- Go to https://api.slack.com/apps → Create New App → From a manifest, and paste
slack-manifest.yaml. - Install it to your workspace and copy the bot token (
xoxb-…). - Under Basic Information → App-Level Tokens, create a token with the
connections:writescope (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, 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
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]:
[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:
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
Run it as a systemd service so the secrets file from step 4 is loaded. Save this as /etc/systemd/system/slackerbot.service:
[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)
- On every node, set the same
[cluster] secret(16+ characters), plus its ownsystem,[[drives]]andhost_reserve, and build the container system there. Slaves don't need Slack tokens oragent_env, because the master sends those, but each needsCLUSTER_SECRETin its own secrets file (step 4). - Master: set
cluster.listen = ":7946"and open the port. On NixOS:services.slackerbot.clusterPort = 7946. - Slaves: set
cluster.master = "wss://<master>:7946"and a uniquecluster.name(default: the hostname). Run with-mode slave. On NixOS:services.slackerbot.mode = "slave". - 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 instate_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.jsonafter the first start, and editing the config doesn't change them. To start over from the config, stop the master and delete thepermissionsentry fromstate.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 fromstate.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>.serviceunit. - Find user and channel IDs in Slack with Copy member ID on a profile, or at the bottom of a channel's About tab.