commit 7822529a389215b19ecfb4bedfce3341d5d3b30c Author: Ari Sosnovsky Date: Sun Nov 1 11:47:41 2026 -0500 first pass diff --git a/README.md b/README.md new file mode 100644 index 0000000..773ff28 --- /dev/null +++ b/README.md @@ -0,0 +1,241 @@ +# slackspawn + +A Slack bot that runs goose agents in NixOS containers and connects them to Slack. + +## Who owns a container + +| Where you talk to the bot | Container | Who can use it | +|---|---|---| +| DM with the bot | `u-` | Only you | +| Channel, private channel or group DM (@mention the bot) | `c-` | Anyone in that channel | + +In channels, every message reaches the agent prefixed with the sender's name (e.g. `Alice: try the other branch`), so it knows who's asking. + +## What happens when someone messages the bot + +1. The bot finds the container for that DM or channel. + - **Running:** uses it. + - **Stopped:** starts it again. Its home folder (`/root`) is still there, and everything else is rebuilt fresh. + - **Doesn't exist:** creates it on the node where CPU, RAM and storage stay most even (see "Running more than one node"), with its home folder on that node's roomiest drive. + - **Everything is full:** replies "maxed out" instead. + - **Its node is offline:** replies "Channel bot is on a dead slave ``, create new container or wait for the slave to be back up?" with **Create new container** and **Wait** buttons. +2. It waits until goose answers on port **1984** inside the container. +3. A new message starts a new agent session, and the reply goes in a thread. + Replying in that thread continues the same session, even days later. +4. The agent's answer streams into the thread as it works, with tool calls shown as `🔧` lines. +5. Every 10 minutes, containers that have gone unused past their limit are shut down. The limit is 6 hours by default, or whatever `keep` set. The owning DM or channel gets a message saying so. +6. Messages in the same thread run one at a time. If two people post at once, the second waits its turn. + +## Commands (send as a new message, not in a thread) + +| Command | What it does | +|---|---| +| `sessions` | Lists this DM's or channel's past sessions with links. Open one and reply in its thread to continue. | +| `status` | Shows the container's state, size, time unused and idle limit, with **Stop** and **Scale up** buttons. | +| `stop` | Shuts the container down. Files are kept. | +| `scale up` / `scale down` | Doubles or halves RAM and CPU. | +| `scale 8G 4cpu` | Sets an exact size. No sign means "set to". | +| `scale +2G` / `scale -1cpu` / `scale 512M +0.5cpu` | A `+` or `-` sign means "change by". Memory and CPU can be mixed or left out. | +| `keep 24h` (or `3d`, `1d12h`, `2w`, `5 hours`) | Stops the container after that long unused, instead of the default. | +| `keep indefinite` (or `forever`) | Never stops it for being unused. Use `stop` when done. | +| `keep default` | Goes back to the config's `idle_timeout`. | +| `keep` | Shows the current idle limit. | +| `storage` | Shows home folder usage, guaranteed space and max. | +| `storage 20G` / `storage +5G` / `storage -2G` | Sets or changes the max (the cap). | +| `storage min 8G` | Sets the guaranteed space. | +| `storage min 8G max 20G` | Sets both. | +| `nodes` | Lists every node with free CPU, RAM and storage, how many containers it has, and which one this container is on. Offline nodes are listed too. | +| `move ` (or `migrate `, `move to `) | Moves this container, running or not, to that node. Works inside a thread too. | +| `permissions` | Shows who can scale, change storage, move or set timeouts in this channel or DM. | +| `move auto` (or just `move`) | Moves it to whichever other node keeps resources most even. | +| `help` | Shows this list. | + +**Scale rules:** memory takes `G`/`GB` or `M`/`MB`, and CPU takes `cpu`/`cpus`/`core`/`cores` (fractions are fine). Sizes stay between 256 MB / 0.25 CPU and `max_container`. Growing a running container needs room on the node. Changes apply live, or on next start if it's stopped. Shrinking memory below what's in use may stop programs inside. + +**Keep rules:** the minimum is 10 minutes. `max_idle_timeout` in the config caps how long `keep` can ask for, and `allow_indefinite = false` turns off `keep indefinite`. Setting `keep` restarts the countdown. + +**Storage rules:** sizes take `M`/`MB`, `G`/`GB` or `T`/`TB`. Both numbers are at least 512 MB, the guarantee can't exceed the max, and the max can't exceed `storage.limit` or go below what's already in use. Raising the guarantee is **rejected** if the drive can't promise it. Raising the max past what the drive can hold for everyone is **allowed but flagged** as overbooked. + +If the words after `scale`, `keep`, `storage` or `move` don't look like a size or a time (e.g. "keep the tests passing"), the message goes to the agent instead. + +Commands act on the container that belongs to where you send them. In a channel, anyone can stop or scale the channel's container. In channels, @mention the bot every time, including in threads. Plain replies aren't seen. + +## Super users and permissions + +Changing a container is limited to super users, one permission at a time: + +| Permission | Covers | +|---|---| +| `scale` | `scale …` and the **Scale up** button | +| `storage` | `storage `, `storage min …` | +| `move` | `move …`, `move auto`, and **Create new container** on a dead slave | +| `keep` | `keep