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-<user id> |
Only you |
| Channel, private channel or group DM (@mention the bot) | c-<channel id> |
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
- 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
<name>, create new container or wait for the slave to be back up?" with Create new container and Wait buttons.
- It waits until goose answers on port 1984 inside the container.
- 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.
- The agent's answer streams into the thread as it works, with tool calls shown as
🔧lines. - Every 10 minutes, containers that have gone unused past their limit are shut down. The limit is 6 hours by default, or whatever
keepset. The owning DM or channel gets a message saying so. - 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 <node> (or migrate <node>, move to <node>) |
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 <size>, storage min … |
move |
move …, move auto, and Create new container on a dead slave |
keep |
keep <time>, keep indefinite, keep default |
all |
The four above (not manage) |
manage |
Changing this channel's super-user list from Slack |
Where they're kept: in the master's state.json. The config's [permissions] are copied in on the very first start and ignored after that, so changes made in Slack stick. To start over from the config, stop the master and delete the permissions entry from state.json.
[permissions]
managers = ["U0ADMIN"] # user managers: can change everything below from Slack
[permissions.default] # used by every channel without its own list
U0ADMIN = ["all"]
[permissions.channels.C07ABC123] # replaces the default list for this channel
U0111 = ["move"]
U0222 = ["all", "manage"] # U0222 also runs this channel's list
[permissions.dm] # what anyone may change on their own DM container
scale = true
storage = false
move = true
keep = true
User managers (managers) can change any channel's list, the default list, the DM flags, and the manager list. Channel managers (manage in a channel's list) can change only that channel's list. At least one user manager is always kept.
Managing from Slack:
| Command | Who | What it does |
|---|---|---|
permissions |
anyone | Shows this channel's (or DM's) super users and the user managers |
grant @alice @bob move scale |
managers of this channel | Grants permissions here. The first grant in a channel copies the default list, so nobody loses access |
revoke @alice move / revoke @alice |
managers of this channel | Takes away some, or all, of someone's permissions here |
permissions reset |
managers of this channel | This channel goes back to the default list |
grant default @alice all / revoke default @alice |
user managers | Changes the default list |
dm storage on / dm storage off |
user managers | Changes what people may do on their own DM container |
managers / managers add @alice / managers remove @alice |
user managers (to change) | Shows or changes the user managers |
People named in a grant, revoke or managers change are tagged in the confirmation, so they're notified.
Other details:
- Showing settings (
storageorkeepwith nothing after them) is open to everyone, as arestatus,nodes,sessions,permissions,stopand talking to the agent. - Automatic moves (when a node is full) don't need a permission.
- Someone without permission gets a short 🔒 reply naming who has it, without tagging them.
- DM flags that are left out count as allowed.
- User and channel IDs: in Slack, use "Copy member ID" on a profile, or the ID at the bottom of a channel's About tab.
Files
| File | 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 |
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 |
Setup
1. Slack app. Create an app from slack-manifest.yaml. Then:
- Install it to your workspace and copy the bot token (
xoxb-…). - Under Basic Information, make an app-level token with the
connections:writescope (xapp-…).
2. Build the container system.
nix build .#nixosConfigurations.agent.config.system.build.toplevel -o /var/lib/slackspawn/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:
imports = [ slackspawn.nixosModules.host ];
services.slackspawn = {
enable = true;
configFile = ./slackspawn.toml; # based on config.example.toml
environmentFile = "/etc/slackspawn/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.
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).
How capacity works
At startup the bot reads total RAM and CPU and subtracts host_reserve. What's left is shared out.
Each running container counts its full limit (memory_mb, cpus) against that.
A container only starts, and scale-up only goes through, if it fits. The startup log prints roughly how many default-size containers fit.
How storage works
Each container's home folder (/root, where goose keeps its settings and session history) is a btrfs subvolume on one of the [[drives]] in the config. That folder is the only thing that persists. Everything else in the container is rebuilt on each start.
Each home has two numbers:
- min (guaranteed): set aside on the drive. A new container is only placed, and a guarantee only raised, if it fits.
- max (the cap): a btrfs quota. Writes past it fail inside the container.
Per drive, the bot works out:
- usable = free space + what homes already use − the drive's
reserve - guaranteed = each home's min, or its real usage if that's bigger
- booked = all the maxes added up
New guarantees must fit in usable − guaranteed. When booked > usable, the drive is overbooked. That's allowed, and status and storage replies flag it, because if every home fills up to its max, writes start failing.
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.
Setup
- Every node needs its own config with
system,[[drives]]andhost_reserve, plus the samecluster.secret(16+ characters). Each also needs the NixOS container build. Slaves don't need Slack tokens oragent_env, since the master sends those. - On the master, set
cluster.listen(e.g.":7946") and open that port. On NixOS, setservices.slackspawn.clusterPort = 7946. - On each slave, set
cluster.master = "wss://<master>:7946"and give it a uniquecluster.name(default: hostname). On NixOS, setservices.slackspawn.mode = "slave". - 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 tostate_dir/master.fingerprint, and refuses any other from then on.
How it works
- Slaves open one TLS WebSocket to the master and keep it open, so they can sit behind NAT. They report their CPU, RAM, drives, home folder usage and running containers every 5 seconds.
- The master starts, stops, resizes and sets quotas on a slave's containers over that link. Agent traffic for a slave's container is relayed over it too.
- A slave that hasn't reported for 20 seconds, or whose link dropped, counts as offline. Slaves reconnect on their own, backing off up to 30 seconds.
Even distribution For each node, the master works out how full it would be after adding the new container: CPU (running containers' CPUs ÷ usable CPUs), RAM (the same), and storage (guaranteed space ÷ usable space on its drives). It takes the worst of the three and places the container where that number stays lowest. Nodes that can't fit the container's RAM, CPU or guaranteed storage are skipped. This keeps all three resources level across nodes, and it naturally avoids a node that's busy on any one of them.
Containers stay on their node until they're moved, because their home folder lives there. scale, storage and restarts all happen on that node. status and nodes show where each container runs and what's free on every node.
Moving a container (move <node>, move auto, or automatically):
- The target must have room for the home folder's guarantee, or its current size if that's bigger. If the container is running, the target also needs room for its RAM and CPU.
- The home folder is snapshotted on the old node and copied with
btrfs send→ master →btrfs receive, in 4 MB pieces. Slaves only talk to the master, so the master relays. - Running containers stay up during the bulk copy. Then the bot waits for any reply in progress to finish (up to 2 minutes), stops the container, copies only what changed since the first pass, and starts it on the new node. Downtime is just that final sync plus a restart.
- The container's record switches to the new node, and the old copy and snapshots are deleted. Sessions carry over, since goose keeps them in the home folder.
- Every move, manual or automatic, starts a new top-level message in the owning DM or channel, that @mentions whoever started it, so they're notified ("started by @Alice"). An automatic move says "started by auto process (master was full)" and tags the person whose message triggered it. Progress goes in that message's thread, and the top message gets the outcome (✅ or ❌) when it's done. The thread where the move was started (under the
movecommand, or the user's own conversation for automatic moves) gets a reply linking to the move thread. - If anything fails before the switch, the half-made copy is removed and the container stays on, and restarts on, its old node. Messages and commands that arrive during a move get "being moved, try again in a moment."
Automatic moves: when a stopped container's node is too full to start it again, the bot moves it to the node with the most room and starts it there, instead of replying "maxed out." Progress shows in the same message.
You can't move off an offline node (the files are there), and a move fails if the target already has an old home folder for that container (e.g. left from "Create new container"). Delete that one first.
When a slave dies, its users get the dead-slave reply. These also get it: stop, scale and storage, plus the Stop and Scale up buttons.
- Create new container: moves the owner to a fresh container on a healthy node. Old threads start new sessions when replied to. The old home folder stays on the dead slave, untouched, and still counts against that slave's drive until you delete it.
- Wait: the bot posts in that DM or channel when the slave reconnects.
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
handleRequestinacp.goto 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.nixusesgoose serve, which needs a recent goose. If nixpkgs'goose-cliis too old, override it with a newer build. - Transport: the bot uses the WebSocket side of goose's
/acpendpoint. If your goose version only offers the HTTP+SSE side,DialACPinacp.gois 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. Swapstore.gofor 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, runbtrfs subvolume deleteon its home, and remove its entry fromstate.jsonwith the bot stopped. Nothing deletes homes automatically, so their guaranteed space stays taken until you do.