# Installation ## Requirements - Linux with systemd (`systemd-nspawn`, `systemd-machined`, `systemd-networkd`), running as root. Containers run with user namespacing and ID-mapped mounts, so you need systemd 250 or newer and a kernel that supports ID-mapped mounts for the filesystems holding `/nix/store`, `state_dir` and the drives (btrfs, ext4 and xfs on any recent kernel). - 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. It has to be a multi-user install with `nix-daemon` running: containers build through `/nix/var/nix/daemon-socket`, and won't start without it. The daemon sees containers as untrusted users (they run as unprivileged host uids), so `trusted-users` needs no changes, but `allowed-users` must still allow everyone (the default `*`). Their builds go into the host's store, so run `nix-collect-garbage` or `nix.gc` now and then. - An API key for the model goose should use (e.g. Anthropic). ## 1. Slack app 1. Go to → **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`, 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`, in-flight replies, 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 ``` ```sh 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]`: ```toml [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: ```nix 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 ``` Or build a static binary with Bazel from a checkout: `bazel build --config=release //slackerbot:slackerbot_tar` produces `bazel-bin/slackerbot/slackerbot_tar.tar.gz`, which holds `usr/bin/slackerbot`. Run it as a systemd service so the secrets file from step 4 is loaded. Save this as `/etc/systemd/system/slackerbot.service`: ```ini [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://: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 /`, 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**. - **In-flight replies** are in `state_dir/in-flight-.json`, one file per channel while it has a reply in progress. The bot picks them back up when it starts. To stop a reply from being resumed, stop the bot and delete its entry (or the file). - **Upgrading** the bot doesn't stop running containers, because each runs in its own `slackerbot-.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.