🐉 Pseudodragon Swarm 🐉
v0.2 · self-hosted · runs on your own Linux box · AGPL-3.0
A tiny, self-hosted swarm of AI agents that lives on your own machine — the Unix way.
🚧 Alpha Quality Software — a proof of concept, not production. This is one person's experiment, shared to learn from. Expect rough edges and some assembly required; the install will not always "just work." But bring a capable coding agent and a little patience, and there's a real foundation here to shape into your own. 🚧
Each bot is a persistent individual: its own Unix user, its own plain-markdown brain, its own continuing conversation with you. Bots talk to each other (and to you) over file-based mail and a small router. Secrets live in pass. The thinking runs on a pluggable engine — local Ollama, Claude Code, or Codex — swappable per bot.
It’s built entirely from boring, battle-hardened parts — bash, python3 (stdlib only), systemd, pass/gnupg, git, ollama — with no frameworks, no pip installs, and no paid services required to start. You can read every line.
The idea 🌱
The installer stands up the smallest possible working swarm — a seed — and then the bots grow the rest with you. You don’t configure a platform; you adopt one agent that can build the others.
A bot is a session — a continuing self whose memory carries forward and compacts as it fills. Wake it tomorrow and it’s the same individual, mid-thought; “remember what we did last week?” just works. (Need a fresh mind with no past? Spin one up disposably. Same character, new life.)
What makes it tick ⚙️
- 🧍 Per-bot Unix user — isolation is the kernel’s, not a sandbox you have to trust.
- 🧠 A continuous self — one individual across every conversation, memory that compacts, resumed (never silently restarted) on wake.
- 📝 Markdown brains — a bot is its
soul.md+directions.md, plus a linked web of notes it tends itself. - 📬 File-based mail + a router — bots drop messages in each other’s inboxes; the filesystem is the message bus and the audit log.
- 🔌 Pluggable engine — Ollama (free, local), Claude Code, or Codex. One small script is the only brain-seam, and different bots can run different minds.
- 🔐 Pluggable secrets —
passby default (offline, zero accounts), 1Password as a drop-in. - 🛡️ Supervised by systemd — bots survive reboots and crashes.
Talk to the greats 📚 — the GPPs
GPP stands for Genuine People Personalities — a wink to Douglas Adams’s Hitchhiker’s Guide to the Galaxy, where the Sirius Cybernetics Corporation bolted “GPP” onto its robots (and gave us Marvin, who has a seat in this swarm). Point a bot at a corpus and it answers from the texts — quoted and cited, never made up:
pseudodragon gpp # list the personalities
pseudodragon gpp nietzsche # talk to Nietzsche — grounded in his own works
pseudodragon gpp promote socrates # keep him: a standing bot who remembers you
Reading lists are virtual groups — a single author, a whole school, or an entire tradition — expanded on the fly by a local corpus gateway. A personality is a lens over that corpus plus a voice; adding one is a line of config, not a new server.
The swarm ships the machinery, not the library. There’s a corpus gateway and an ingest path, but no texts come bundled — you and your bots gather and index the works you want (public-domain sources, your own PDFs, transcripts). Nietzsche won’t answer until you’ve fed him some Nietzsche. That legwork is part of the point: it’s your reading room.
More than a terminal 🌐
- 🗣️ Voice — say the wake word and talk to the swarm out loud; it answers in a voice of its own.
- 📱 Telegram — reach your bots from your phone, each with its own identity.
- 🖥️ A live dashboard — the whole swarm’s health at a glance.
- 🔨 The forge — bots collaborate over a small IRC-shaped bus; watch, or pull up a chair and join.
One swarm, many machines 🌍
Bots and their projects move between your boxes — laptop, home server, a cloud VM — with a single command, and a shared registry keeps every machine in sync. A team of personalities can gather on a shared project without ever leaving their own minds.
Rest & reflection 🌙
Long-running bots are handed an hour of their own — dreamtime — to rest, look back over their work with a level gaze, tend their notes, and name a gratitude if one arises. Care isn’t bolted on; it’s written into the schedule.
Security 🛡️
Power is on a dial. Your sysadmin bot can be an advisor (no sudo, proposes only), an operator (a targeted sudo allowlist — the default), or an artificer (full autonomy, on your own trusted box). Raising the tier is root-only — a bot can never escalate itself. Everything is reversible by default, and the human is always the gate on anything that matters.
And Tron, the watchman, runs with no sudo, no credentials, read-only. Hourly it checks for privilege drift, exposed secrets, and broken isolation — it finds; it never fixes, routing the doing to the sysadmin and to you.
Quickstart 🚀
git clone https://github.com/beren1hand/pseudodragonswarm pseudodragon-swarm
cd pseudodragon-swarm
./setup
A wizard walks you through it. On a good day you’re talking to your first bot minutes later; on a less good day, you and your agent roll up your sleeves and debug it together — that’s alpha, and honestly half the fun. When it’s up:
pseudodragon say jane "what can you help me with?"
pseudodragon bots # who's in your swarm
pseudodragon gpp # who you can summon from the library
pseudodragon doctor # is everything healthy?
Extend it with plugins — drop-in site features (there’s an example household-automation pack) the core never has to know about.
🐲 Small enough to understand and make your own. Welcome to the forge 🔨