5.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.
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:
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)
- 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. - 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.