2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00
2026-11-01 11:47:41 -05:00

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

  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 <name>, 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 <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 (storage or keep with nothing after them) is open to everyone, as are status, nodes, sessions, permissions, stop and 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:write scope (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

  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".
  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

  • 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):

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 move command, or the user's own conversation for automatic moves) gets a reply linking to the move thread.
  6. 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 handleRequest in acp.go 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.
  • 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.
  • 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.
S
Description
No description provided
Readme
7.9 MiB
0 Stars 1 Watchers 0 Forks
Languages
Go 95.3%
Starlark 3.2%
Nix 1.4%