Files
slacker-bot/INSTALLATION.md
T

7.3 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

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

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