7.1 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.
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 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.