arizuko

arizuko hosts many specialized agents on one platform — each a folder with its own persona, skills, and memory, each shaped by talking to it. You say what you want; an LLM edits the files that are the agent. The conversation is the console.

arizuko is simple on purpose, and the simplicity is the reason it is flexible. An agent is a folder of plain files. A route is a row in the store, the database of the instance, that sends the messages of one chat to one folder. A grant is a row that lets one person or agent do one action. You read a folder as files and a row with the arizuko command.

Daemons do the work around the folders. A daemon is a program that runs in the background all the time, and its name ends in “d”. routd decides which folder answers a message. runed runs each turn in its own KVM guest, a small virtual machine that exists for that one turn. A turn is one run of an agent. authd signs identity tokens. One directory on your server holds the folders and the store. You change an agent in chat, then read the result in its files.

The setup guide builds the images, creates an instance, initializes the store and starts the instance. To select a product, add --product slack-team to the guide's create command. routd selects the product for the main group at its first boot. After that, arizuko package sync installs the product files.

The setup guide also covers the chat connection. See all products and the source on GitHub. arizuko is free under the MIT license.

krons, at https://krons.fiu.wtf, is the reference deployment. The maintainers run it, every release deploys there first, and it serves these docs at https://krons.fiu.wtf/pub/arizuko/.

a product is an agent you install and own

A product is a folder of persona, skills, routes and knowledge. The catalog has fifteen products. Eleven install with arizuko create --product, and four describe a setup you build yourself. Three of them:

Eight more products ship as templates in the catalog: a support desk, a personal assistant with memory, a PM board and a domain researcher among them. Four products are shapes without a template, and one page describes them.

many agents run side by side

Those three are three folders in one instance, not three installs. Each folder keeps its own persona, memory, grants and secrets.

each turn runs in its own guest behind a proxy

Every turn runs in a fresh KVM guest. Outbound traffic leaves through the egress proxy of that guest, a proxy that forwards only the host names in the allowlist of the folder. runed starts one proxy per turn and refuses to start without the proxy binary. The network interface of the guest drops every packet that skips the proxy, and the guest has no DNS resolver, the service that turns a host name into an address. A support agent can face strangers on a public channel and keep its own history.

A normal turn does not receive the home folder of another agent. Two mounts share files across agents:

• Every turn of one world mounts the same writable directory at /var/lib/share. A world is the top-level folder of a path. A share_mount grant with readonly=true makes it read-only for one folder.
• An elevated operator turn mounts every group at /var/lib/groups.

agents hand work down and up the folder tree

An agent hands a prompt down to a child folder, such as corp/eng/sre below corp/eng, or up to its parent folder. Every link needs a grant. The child runs its own turn in its own KVM guest, so each sub-agent gets a machine of its own. A child folder runs in its own guest gives the limits.

one chat can move between agents

Send @acme/sales on its own, and the whole chat goes to the sales agent. A bare @ resets the routing to the default.

every event takes the same six steps

A Slack mention in #eng, a scheduled task, a webhook and an email all take these steps in this order. The Slack mention ends as a reply in the Slack thread.

1. An event becomes one row in the inbox: a chat message, a call from another service or a clock tick.
2. The route table maps the event to the folder that answers. The first matching route wins.
3. The folder loads its persona, skills and memory.
4. One question decides authorization: may this person or agent do this action here? A grant row answers it.
5. A fresh KVM guest runs the agent once and powers off. The guest sees only the files shared into it and reaches only the hosts its proxy allows.
6. The store keeps the rows, and the folder keeps the files.

An observe route stores the message and fires no turn. The six steps in full →

you own the files

An instance is one directory. Everything the system is lives in it:

/srv/data/arizuko_demo/
├── .env                 tokens and config
├── store/               every row, on the store server of the instance
│   ├── extenddb/        the server’s config and certificate
│   └── extenddb_db/     its PostgreSQL data
├── groups/
│   ├── main/            one agent
│   │   ├── PERSONA.md   who it is
│   │   ├── CLAUDE.md    how it operates
│   │   ├── .claude/skills/  what it can do
│   │   ├── facts/       what it has learned
│   │   └── diary/       what happened, dated
│   └── ops/             a second agent, same shape, its own memory
└── web/pub/             public pages, one folder per agent, and these docs

Edit the persona file, and the next turn uses it. Stop the instance, and one tar of the directory is a complete backup: every row, every memory, the secrets and the site. The platform does not version the folders. Put groups/ under git yourself, and each change the agent makes shows as a diff, the list of lines that changed. The agent image ships git and a commit skill.

what arizuko needs and what it does not do

• One Linux host with Docker and KVM runs it. The daemons run as Docker Compose services, and each turn is a KVM guest, so the host needs /dev/kvm. Compose on one host is the tested path. A Helm chart, the install recipe for Kubernetes, exists, and no cluster has run it.
• You pay for the host and the model. arizuko is free software. The model provider bills the key you supply. The default network allowlist opens anthropic.com and api.anthropic.com.
• arizuko is self-hosted only and serves teams of agents behind chat channels, not consumer traffic. The [README] lists what it does not include.
• The store server runs ExtendDB, a database server for the DynamoDB protocol that keeps its data in PostgreSQL. A daemon without a store key exits, and runed does not start without /dev/kvm. A minimal deploy is the store server, authd, routd, runed, timed and one channel adapter. The web daemons start when you set WEB_PORT, and onbod starts when you turn onboarding on.
• An agent calls platform actions as MCP tools, the Model Context Protocol for agent tools. A person or script calls the same actions as REST, ordinary web requests at /v1/<name>. Actions that only an agent uses in a turn, such as reply and send, exist as MCP alone.
• One TOML block, a short settings text, gives an agent the API of another service as a tool. The call leaves from the host, the host adds the secret, and the secret never enters the guest. Connectors has the detail.

where to read next

• concepts — one idea per page; start with the six steps.
• products — all fifteen, an intro and a setup page each.
• components — one page per daemon: routd, runed, authd, the channel adapters, and the rest.
• reference — env · CLI · MCP tools · schema · grants · JID.
• howto — install, first channel, first message.
• changelog — what shipped, dated.
• security — the threat model and the operator’s side of it.
• comparable systems — how each overlapping system differs from arizuko, and arizuko’s open limits.
• research — write-ups on architecture, security, patterns and skills.
• Repository files: SECURITY.md and ROUTING.md.

MIT · Go, Docker and KVM.

updated 2026-10-21