clean up of the codebase

This commit is contained in:
ari committed 2026-11-01 13:01:54 -05:00
1 parent 7822529a38
commit 0ac61b4ece
52 files changed
+2545 -2274

No files matched your search

+39 -34
View File
@@ -1,4 +1,4 @@
# slackspawn
# slackerbot
A Slack bot that runs goose agents in NixOS containers and connects them to Slack.
@@ -118,29 +118,34 @@ People named in a `grant`, `revoke` or `managers` change are tagged in the confi
## Files
| File | What's in it |
All Go code lives in `slackerbot/` (the Go module root). Each package under `slackerbot/internal/` does one job:
| Package | What's in it |
|---|---|
| `main.go` | Startup: config, capacity check, Slack connection |
| `config.go` | Reads `config.toml` |
| `capacity.go` | Reads the node's RAM/CPU and decides whether another container fits |
| `node.go` | What every node (this machine or a slave) can do |
| `local.go` | Runs containers on this machine (`systemd-run` + machined over D-Bus, btrfs homes) |
| `manager.go` | Owners, placement, resizing and storage across all nodes |
| `balance.go` | Picks the node that keeps CPU, RAM and storage most even |
| `cluster.go` | The master/slave link: TLS WebSocket, calls, agent relay, certificate pinning |
| `migrate.go` | Moving a container between nodes |
| `transfer.go` | Copying a home folder with btrfs snapshots, send and receive |
| `acp.go` | Talks to goose (ACP over WebSocket at `/acp`) |
| `stream.go` | Streams agent replies into Slack by editing messages |
| `bot.go` | Slack events, commands, buttons, idle cleanup |
| `commands.go` | Understands `scale` sizes and `keep` times |
| `permissions.go` | Super users and per-action permissions |
| `manage.go` | `grant`, `revoke`, `dm`, `managers` and `permissions reset` |
| `storage.go` | Home folder sizes, btrfs quotas, and the drive math |
| `store.go` | Remembers owners (DMs and channels), sessions, last activity and permissions in `state.json` |
| `config` | Reads `config.toml` |
| `model` | Shared types: sizes, owners, sessions, super users and per-action permissions |
| `units` | Reads and prints sizes like `5G` |
| `commands` | Understands `scale`, `keep`, `storage` and `grant` messages |
| `storage` | Drive math, btrfs subvolumes and quotas |
| `state` | Remembers owners (DMs and channels), sessions, last activity and permissions in `state.json` |
| `node` | What every node (this machine or a slave) can do |
| `local` | Runs containers on this machine (`systemd-run` + machined over D-Bus, btrfs homes, send/receive), and reads its RAM/CPU |
| `balance` | Picks the node that keeps CPU, RAM and storage most even |
| `manager` | Owners, placement, resizing and storage across all nodes; the master/slave link (TLS WebSocket, agent relay, certificate pinning); moving containers |
| `acp` | Talks to goose (ACP over WebSocket at `/acp`) |
| `bot` | Slack events, commands, buttons, idle cleanup, streaming replies, `grant`/`revoke`/`dm`/`managers` |
| `util`, `testutil` | Small helpers, and fakes for tests |
| `nix/container.nix` | The NixOS system each container boots, with goose on 1984 |
| `nix/host.nix` | Host module: runs the bot and gives containers a network |
## Development
`nix develop` gives a shell with Go, gopls and the other tools. Then, inside `slackerbot/`:
```
go build ./... && go vet ./... && go test ./...
```
## Setup
**1. Slack app.** Create an app from `slack-manifest.yaml`. Then:
@@ -149,22 +154,22 @@ People named in a `grant`, `revoke` or `managers` change are tagged in the confi
**2. Build the container system.**
```
nix build .#nixosConfigurations.agent.config.system.build.toplevel -o /var/lib/slackspawn/agent-system
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.
**3. Host config.** Add the flake's `nixosModules.host` to your host:
```nix
imports = [ slackspawn.nixosModules.host ];
services.slackspawn = {
imports = [ slackerbot.nixosModules.host ];
services.slackerbot = {
enable = true;
configFile = ./slackspawn.toml; # based on config.example.toml
environmentFile = "/etc/slackspawn/secrets"; # SLACK_APP_TOKEN=…, SLACK_BOT_TOKEN=…, ANTHROPIC_API_KEY=…
configFile = ./slackerbot.toml; # based on config.example.toml
environmentFile = "/etc/slackerbot/secrets"; # SLACK_APP_TOKEN=…, SLACK_BOT_TOKEN=…, ANTHROPIC_API_KEY=…
};
```
On the first build, Nix will complain about `vendorHash`. Paste the hash it prints into `flake.nix`.
After changing Go dependencies, update `vendorHash` in `flake.nix` (Nix prints the new one on the next build).
**Not using NixOS for the host?** Run `go build`, then start `./slackspawn -config config.toml` as root. Make sure systemd-networkd manages `ve-*` links (systemd ships `80-container-ve.network` for this).
**Not using NixOS for the host?** Run `nix build .#slackerbot` (or `go build` inside `slackerbot/`), then start `slackerbot -config config.toml` as root. Make sure systemd-networkd manages `ve-*` links (systemd ships `80-container-ve.network` for this).
## How capacity works
@@ -192,13 +197,13 @@ Every drive must be btrfs. The bot turns on quotas for each drive at startup.
## Running more than one node
One binary, two modes:
- `slackspawn -mode master`: runs the Slack bot and also runs containers itself.
- `slackspawn -mode slave`: runs containers only, for the master it points at.
- `slackerbot -mode master`: runs the Slack bot and also runs containers itself.
- `slackerbot -mode slave`: runs containers only, for the master it points at.
**Setup**
1. Every node needs its own config with `system`, `[[drives]]` and `host_reserve`, plus the same `cluster.secret` (16+ characters). Each also needs the NixOS container build. Slaves don't need Slack tokens or `agent_env`, since the master sends those.
2. On the master, set `cluster.listen` (e.g. `":7946"`) and open that port. On NixOS, set `services.slackspawn.clusterPort = 7946`.
3. On each slave, set `cluster.master = "wss://<master>:7946"` and give it a unique `cluster.name` (default: hostname). On NixOS, set `services.slackspawn.mode = "slave"`.
2. On the master, set `cluster.listen` (e.g. `":7946"`) and open that port. On NixOS, set `services.slackerbot.clusterPort = 7946`.
3. On each slave, set `cluster.master = "wss://<master>:7946"` and give it a unique `cluster.name` (default: hostname). On NixOS, set `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 to `state_dir/master.fingerprint`, and refuses any other from then on.
**How it works**
@@ -229,13 +234,13 @@ You can't move off an offline node (the files are there), and a move fails if th
## Things to know
- **The agent's actions are auto-approved.** When goose asks permission to run a tool, the bot says yes, since the container is the sandbox. To ask the user instead, change `handleRequest` in `acp.go` to post Slack buttons.
- **The agent's actions are auto-approved.** When goose asks permission to run a tool, the bot says yes, since the container is the sandbox. To ask the user instead, change `handleRequest` in `slackerbot/internal/acp` to post Slack buttons.
- **Anyone in a channel controls its container,** including everything the agent can reach from it. Only add the bot to channels whose members you'd trust with that.
- **Containers run as root without user namespaces.** They're isolated, but not strongly enough for people you don't trust. For untrusted users, look at nspawn's `--private-users=pick` (not turned on here, since it needs testing with a shared `/nix/store`).
- **goose version:** `nix/container.nix` uses `goose serve`, which needs a recent goose. If nixpkgs' `goose-cli` is too old, override it with a newer build.
- **Transport:** the bot uses the WebSocket side of goose's `/acp` endpoint. If your goose version only offers the HTTP+SSE side, `DialACP` in `acp.go` is the one place to change.
- **Transport:** the bot uses the WebSocket side of goose's `/acp` endpoint. If your goose version only offers the HTTP+SSE side, `DialACP` in `slackerbot/internal/acp` is the one place to change.
- **btrfs quotas aren't a hard security boundary here.** Container root keeps enough privileges that a determined user could raise their own quota. They're good for fair sharing, not for hostile users.
- **Restarting the master** briefly makes every slave look offline until they reconnect, which takes a few seconds. Messages in that window get the dead-slave reply.
- **Restarting the bot doesn't stop containers.** They run as their own systemd units (`spawn-u-….service`), and the bot reconnects on the next message.
- **State** is a small JSON file (`state_dir/state.json`). It's fine for hundreds of users. Swap `store.go` for SQLite if you need more.
- **Restarting the bot doesn't stop containers.** They run as their own systemd units (`slackerbot-u-….service`), and the bot reconnects on the next message.
- **State** is a small JSON file (`state_dir/state.json`). It's fine for hundreds of users. Swap the `state` package for SQLite if you need more.
- Home folders live at `<drive path>/u-<id>` or `<drive path>/c-<id>`. To wipe one for good, stop the container, run `btrfs subvolume delete` on its home, and remove its entry from `state.json` with the bot stopped. Nothing deletes homes automatically, so their guaranteed space stays taken until you do.