# 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 → **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: ```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"; # 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://: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**. - **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.