Files
2026-11-02 15:29:11 +00:00

88 lines
4.3 KiB
Markdown

# Slackerbot
Slackerbot is a meta-harness that handles users ACLs, sandbox management and session persistance accross system reboots.
Talk to the bot in Slack, and your message goes to a [goose](https://github.com/block/goose) agent inside a `systemd-nspawn` container. The agent's reply streams back over ACP into a Slack thread. Replying in that thread continues the same session. Different additional tools can be exposed to the agent depending on the user's access level. One container serves all different sessions for a channel.
- **One container per DM or channel.** DMs get a private container, and channels share one.
- **Access Controls** different users may be given privillege access in certain channels, access is delegated by "manager users" via configuration or with the bot.
- **Persistent home folder.** `/root` lives on a btrfs subvolume with a guaranteed size and a cap. Everything else is rebuilt on each start.
- **Managed from Slack.** Users can `scale`, `stop`, set idle timeouts with `keep`, resize `storage`, and `move` containers between nodes. Changes are limited by per-channel permissions.
- **Scalable** A master runs the Slack bot, and slaves add capacity. New containers go wherever CPU, RAM and storage stay most even, and live migration moves a running container with only a short pause.
## Top Level Design
```mermaid
flowchart LR
slack([Slack]) <-->|Socket Mode| bot
subgraph master["Master host"]
bot[bot] --> mgr[manager]
bot <-->|ACP over WebSocket| acp[acp client]
mgr --> local1[local node]
mgr --> state[(state.json)]
local1 -->|systemd-run + machined D-Bus| c1["nspawn: c-…<br/>goose serve :1984"]
local1 -->|btrfs subvolume + quota| d1[(drives)]
end
subgraph slave["Slave host (0..n)"]
local2[local node] --> c2["nspawn: u-…<br/>goose serve :1984"]
local2 --> d2[(drives)]
end
acp -.->|direct| c1
mgr <==>|"TLS WebSocket (slave dials out)<br/>calls · reports every 5s · agent relay · btrfs send/receive"| local2
acp -.->|relayed over the link| c2
```
## Docs
| File | For |
| ---------------------------------- | -------------------------------------------------- |
| [INSTALLATION.md](INSTALLATION.md) | Setting up the Slack app, the host and extra nodes |
| [USERGUIDE.md](USERGUIDE.md) | Slack commands and how permissions work |
| [ARCHITECTURE.md](ARCHITECTURE.md) | How the system and the code are put together |
| [AGENTS.md](AGENTS.md) | Rules for changing the code: tests, layout, style |
# Technology Choices
- [Goose Agent](https://github.com/block/goose)
- Builtin ACP Support: can spin up and manage multiple sessions via a websocket connections between the host and children
- Builtin support for most LLM provider out of the box
- Systemd NSpawn Containers with shared nix-store and bazel cache
- Lightweight virtulization
- Ability to set limits and requests for resources dynamically
- BTRFS Volumes
- Bultin backups via snapshots
- Ease of moving snapshots between host nodes
- Ease of extending storage capacity using RAID
- Custom Agent Scheduler
- Need extended support for ensuring agent sessions can survive a reboot
- Need extended support for managing user access controls to tools exposed by the meta-harness
- Need a simple clustering and scheduling solution that is purpose built for always-on agents
- Nix
- Easy reproducible rollouts
- Ensure the same version of packages like bazel is installed on the host and guest machines
- Allow the guest to pull any tools they want and reuse packages already installed on the global nix-store, which is effectively a massive cache
# Toplevel Access Controls
```
User managers ──── edit all lists, DM switches, managers
│
▼
Channel list (or the default list) DM switches
names who can scale · storage · on/off per action
move · keep · manage for your own DM container
│ │
▼ ▼
Change a channel container Change your DM container
Everyone: talk to the agent, view status, stop, cancel
Agent tool calls: checked as the person it's answering
```