Files
slacker-bot/INSTALLATION.md
T
2026-11-01 13:13:04 -05:00

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

  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.

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)

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