arizuko

Run persistent AI agents on your own host. Each folder is an agent with its own persona, memory, skills, routes, and files. Agents and operators use the same MCP tools and REST endpoints. gated checks every call.

agents as data

An agent is a folder of files the LLM loop reads. The persona is a file. Memory is a file. Skills are directories. Config is a file you can diff, review in a PR, and roll back with git revert. The org chart is the folder tree.

Each folder is a context boundary: corp/sales doesn’t see corp/eng/sre’s memory. Change the persona by editing a file; the next session picks it up. Add a skill by dropping a directory. Everything an agent knows or can do is readable, inspectable, and replaceable.

Agents need structure the same way humans do — not bureaucracy, but enough to know what they can reach, what their job is, and who they answer to. Minimality and orthogonality provide that: one concept per primitive, nothing hidden, everything composable. A system simple enough for a human to reason about is simple enough for an agent to manage. That’s the design principle arizuko is built around.

why not a shared assistant?

• Wrong replies land in the thread — one assistant reads sales, support, and ops history from the same memory.
• Old context changes new work — unrelated threads stay attached unless somebody clears them.
• Your system lives in Slack, email, and files — one shared assistant sees one thread, not the whole operating surface.
• Failures are hard to inspect — there’s no file to diff, no route to trace, and no clean rollback.

arizuko gives each team its own agent, memory, channels, and policy on your own host. Config is files. Rollback is git revert.

how it works

A folder is an agent: PERSONA.md, a skills/ set, memory files, and an ACL row. When a message arrives, a Docker container starts for the folder and connects to gated via MCP over a unix socket. Every tool call goes through that socket; the host controls what the agent can reach. Every platform operation is an MCP tool and a REST endpoint — no separate agent API. All state is in SQLite WAL; the container is stateless.

The stack is sized for agent teams: dozens of messages a day, not web-scale traffic. Go binaries, Docker Compose, SQLite WAL, proxyd signing identity headers — no Auth0, no Redis, no Vault.

organize

• Agents as folders. corp/sales, corp/eng/sre, corp/support — each a directory with a prompt file, a memory file, and a skill set. Add a folder, get an agent.
• Personality, skills, and memory. Each folder has a PERSONA.md (voice and instructions), a skills/ set, and memory that accumulates across weeks. An agent that helped close a deal in January remembers it in March.
• Topics that fork. Spin a side-conversation off any thread — the new topic carries the parent’s conversation as its starting context. Parallel workstreams, no context loss.
• Agents that commission agents. A root agent can create a child group on first contact, assign routes, and schedule tasks — using the same MCP tools a human operator would invoke. Deploy a per-customer support agent automatically — no automation logic to write.

ingest

• Any surface works. Drop files via WebDAV, send a message in chat, email the agent’s address, or POST to a webhook — they all arrive as messages in the same folder. No import wizard, no format conversion.
• Agents grow their own knowledge. When an agent researches something mid-conversation, it writes the findings to its own facts/. The next session, it already knows. No admin step, no sync job.
• Every system can feed it. Issue a webhook token for any folder and pipe in alerts, tickets, or CRM events — they arrive as messages and the agent decides what to retain.

coordinate

• Agents talk to each other. Route a message from support to eng, delegate work to a child, escalate to a parent. delegate_group, escalate_group, and observe_group are MCP tools built around the same coordination protocols a human operator would use.
• Schedule tasks. Cron-style tasks per folder — daily summaries, weekly reports, autonomous background work — each running with the folder’s full memory and persona. Set up by the agent itself or from the dashboard.
• Webhooks as messages. POST to /hook/<token> from any external system — the payload lands as a message in any folder. Pair with a scheduled curation agent: no custom integration code, just a prompt and a cron.
• Acts on knowledge, doesn’t just answer questions. A curation agent reads your Slack intake, decides what matters, and writes a daily brief. A support agent remembers every customer interaction and escalates without being asked. That’s not a knowledge base — that’s an agent with memory and a job.

connect

• Channel-native adapters. Each adapter speaks the platform’s own API: Telegram bot API, Discord gateway, WhatsApp web, IMAP/SMTP, Mastodon streaming, Bluesky AT Protocol. Not a webhook relay — the adapter owns the connection and surfaces events (threads, reactions, voice messages) that webhooks can’t express. Also: Slack (slakd, AI assistant pane), Reddit (reditd), X/Twitter (twitd), LinkedIn (linkd).
• Public chat and webhook surfaces. Issue a route token and any folder gets a /chat/<token>/ page (SSE, works in a browser) and a /hook/<token> endpoint (POST JSON, fires the agent). No extra config.
• Everything meets at messages.db. Routes match on key=glob. ACL is one row: (principal, action, scope, params). Siblings see each other’s observed messages unless the group is closed. Channels speak HTTP. No hidden state elsewhere.

operate

• MCP over a unix socket. Every agent connects to gated via a MCP unix socket bridged into the container. Tool calls go through that socket; the host controls what the agent can reach. Side effects are auditable, revocable, and scoped to the folder’s grant rules.
• Operator dashboard. /dash/ — routes editor, task scheduler, per-group model selector (Opus / Sonnet / Haiku), skill toggles, grants editor, invite management, usage metrics, and secrets (AES-256-GCM encrypted at rest). No editing .env by hand to rewire a route.
• Egress sandboxing. crackbox wraps each container with a per-folder hostname allowlist, HTTPS via CONNECT, and DNS filtering. The agent can only reach what you explicitly permit. See crackbox.

start small, grow into it

A minimal deploy is gated and one channel adapter. Add components as you need them — each is a standalone binary with its own TOML block. There’s no managed control plane; every piece is replaceable.

Setup	What runs	Best for
Minimal	gated + one adapter	First deployment, one team
Standard	+ dashd + timed	Ongoing ops, scheduled tasks
Multi-team	+ onbod + crackbox	Isolated teams, egress control
Product recipe	Pre-seeded config	slack-team, reality — 5 minutes

One tar of /srv/data/arizuko_<name>/ backs up the entire instance: messages.db (WAL), group folders, per-user memory, secrets, agent files.

show me

# seed the instance directory
arizuko create demo
# /srv/data/arizuko_demo/ now has .env, store/, groups/, ipc/, web/pub/

# pick adapters + tokens
$EDITOR /srv/data/arizuko_demo/.env

# register the first group's inbound JID
arizuko group demo add tg:-123456789 main

# render docker-compose.yml from .env + extras, then bring it up
arizuko run demo
# systemd unit: arizuko_demo (sudo systemctl status arizuko_demo)

# talk to the default group from a browser
arizuko token issue demo chat   # prints a /chat/<token>/ URL

# or from a script — same endpoint, JSON in / JSON out
curl -X POST https://example.com/chat/<token>/ \
  -H 'Content-Type: application/json' \
  -d '{"text":"hello"}'

go deeper

• products — curated configurations: Slack team agent, support bot, content pipeline, PM board, and more.
• components — one page per daemon: gated, webd, proxyd, dashd, onbod, timed, plus the channel adapters.
• concepts — the primitives one page each: topics, scopes, routing, grants, auth, jid, tasks, secrets, personas, skills, onboarding, slack pane, route tokens, webdav, voice.
• reference — every configurable surface, grep-verified against source: env · CLI · MCP tools · schema · grants · JID.
• howto — deployment guide, first channel, first invite, verification.
• crackbox — the egress-isolation sandbox: per-folder hostname allowlist, HTTPS via CONNECT, DNS filter.
• changelog — what shipped, dated.
• Source: github.com/kronael/arizuko (MIT). Threat model in SECURITY.md; routing rules in ROUTING.md.

v0.44.0 · MIT · Go + SQLite (WAL) + Docker · running on krons, marinade, sloth.