clean up of the codebase
This commit is contained in:
1 parent
7822529a38
commit
0ac61b4ece
52 files changed
+2545
-2274
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user