Arizuko Research

Multi-tenant agent platform architecture, security model, coordination patterns, and skill development

System Model

Folders are agents. Each folder is a tenant: isolated memory, persona, skills, routes. MCP over unix socket. Tool calls go through `gated`; host controls what agents can reach. Defense-in-depth. Container isolation + DNS filtering + per-group MCP sockets + the host-side secret broker.

What brings you here?

🏗️ Architecture Tenancy, routing, groups/topics/sessions 🔒 Security Egress filtering, MCP isolation 🔄 Patterns Coordination, dispatch, resume tokens ⚡ Skills MCP tradeoffs, marketplace, evals

Architecture

Tenancy Model

Each folder is a tenant. A folder path is a routing target, a JID prefix, a container home and a web vhost — it carries no authority. Authority is a row in the acl table:

Principal	Holds	Authority
`role:member`	The twelve messaging verbs	Bound to every folder at creation. Reply, send, post, like, edit and the rest — nothing more.
`role:operator`	`` on `*`, WITH GRANT OPTION	The root of every delegation chain. Held by a person, invoked with `/root`.
`folder:world/team`	Whatever was delegated to it	Routing, group creation, token issuance, egress — each an explicit row, each bounded by its own scope glob.

routd evaluates every tool call against those rows, deny-wins, with no fallback: an action with no matching allow row is refused. Delegation is bounded by subset-of-held — a principal may pass on only rows it holds, and only those it holds with the grant option — so authority strictly decreases down every chain and no agent can escalate past its granter.

Execution Model

When a message arrives:

Gateway matches route predicates (platform=, chat_jid=, sender=)
Starts a Docker container for the matched folder
Mounts /home/node/ (group workspace), /workspace/web/ (optional web surface)
Bridges MCP unix socket from host into container
Claude Code agent runs; all tool calls go through gated via MCP socket
Container exits after turn completes; workspace persists

Containers are ephemeral. All state is in /home/node/ (volume-mounted) or routd's message store, which is host-side.

Groups, Topics, Sessions

Groups are folders. Topics scope conversations within a group. Sessions are Claude Code's execution context. Fork a topic to branch a conversation while preserving parent context.

Routing

Routes are rows in routes table with seq (priority), match (key=glob predicates), and target (folder or :daemon:).

seq  match                          target
100  platform=telegram room=main    corp/sales
200  platform=slack                 corp/eng
300  chat_jid=web:*                 :daemon:webd

First match wins. gated resolves predicates at message-receive time. Engagement overrides routing for N turns after a reply.

Observable Architecture

Groups can observe other groups' inbound messages without becoming the active agent:

observe_group(source) — subscribe to another folder's messages
set_group_open(true) — expose this group to sibling ambient context
Observed messages surface in <observed> blocks (gateway-injected)

Use for parent monitoring children, sibling awareness, or root aggregation. Observed context is capped per turn (env: OBSERVE_WINDOW_MESSAGES, OBSERVE_WINDOW_CHARS). See spec 5/B.

Security

Threat Model

Arizuko assumes:

Agents are untrusted. LLM output can be malicious or compromised.
Tool calls are the attack surface. Every MCP tool call is a potential privilege escalation.
Network egress is risk. Agents can exfiltrate data if unrestricted.

Defense: isolation at container, network, MCP, and secret layers.

Defense-in-Depth

Primitive	Lifecycle	Isolation	Use
Group	Persistent	Folder boundary	Agent identity, memory, persona, skills
Topic	Transient	Session ID	One conversation thread, forkable
Session	Ephemeral	Claude Code session	LLM context window, reset via `/new`

Layer	Mechanism	Threat Mitigated
Container	Docker isolation, no `--privileged`	Process escape, host filesystem access
Network	Per-spawn proxy on an `internal` network + host allowlist	Exfiltration, C2 communication
MCP	Per-group unix socket, grants enforced by `gated`	Cross-tenant tool access, privilege escalation
Secrets	AES-256-GCM at rest, env-var injection, no disk persistence	Secret theft via disk access or container inspect

Egress filtering

Per-folder allowlist, enforced by a proxy started fresh for each spawn:

No route out: the spawn's network is created --internal, so the proxy is its only path anywhere
Host matching: exact, subdomain-aware and case-insensitive, read from the request line
CONNECT tunnelling: HTTPS is spliced, never decrypted — no CA, no key material, no request bodies
One client: the proxy answers that spawn's address and 403s every other peer, including sibling spawns

The agent reaches only what the operator permitted. Example allowlist: ["api.anthropic.com", "github.com", "pypi.org"]. See egress docs and SECURITY.md.

MCP Socket Isolation

Each group gets its own unix socket (/ipc/<group_id>.sock). gated brokers every tool call, enforces grants, and logs actions. Agents cannot reach other groups' sockets — Docker mounts only the agent's own socket.

Secrets

Secrets are AES-256-GCM encrypted in the secrets table in routd.db. The container env carries model credentials only — the four env-profile keys, taken from the host .env and overlaid with the triggering user's own rows. Every capability credential stays on the host: routd resolves it per tool call, spends it in the outbound request, and returns only the response. No secret is written to /home/node/ or to logs.

Patterns

Agent-to-Agent Coordination

Three MCP tools for hierarchical coordination:

delegate_group(group, prompt, chatJid) — hand work down to a child. Child runs async, parent doesn't block.
escalate_group(prompt, chatJid) — hand work up to parent. Parent responds back through this child.
observe_group(source) — watch another group's messages without taking over.

Use delegate for specialist work. Use escalate when authority is needed. Use observe for ambient awareness (sibling monitoring, aggregation).

Topic Forking

fork_topic(parent, child) — create a new topic from another's session state. Child gets a fresh session ID but starts with parent's Claude Code context. Use for:

Side-conversations that need parent context
Parallel workstreams without polluting parent
Focused exploration that can later merge findings back

Dispatch Trigger Design

Skills can specify ALWAYS or NEVER triggers in SKILL.md:

ALWAYS:
- "download this video" → acquire
- "transcribe this" → acquire

NEVER:
- Static pages → do NOT use agent-browser, use acquire instead

Gateway reads these at session start and surfaces them in <skills> block. Agent uses them for fast dispatch without re-reading every SKILL.md.

Stateless Iteration Loops (Ralph)

Pattern for long-running tasks that survive session resets:

Write progress to ~/state/.json
Each turn: read state, process next batch, write state
On session reset: re-read state, continue from last checkpoint
No in-memory state — stateless across turns

Named after "ralph loop" (stateless iteration). Use for multi-page scrapes, batch processing, or any task that takes >1 session.

Resume Tokens

For APIs with pagination or long-running operations:

Store resume token in ~/state/ or ~/facts/
On next turn, check for token, resume from checkpoint
Example: GitHub API pagination (page=N), Stripe list cursors

Fingerprint-Based Change Detection

Detect file changes without storing full content:

Compute SHA-256 of file, store in ~/state/fingerprints.json
On next turn, recompute and compare
Only process changed files

Use for monitoring codebases, watching config files, or tracking external resources.

Multi-Agent Pipeline Orchestration

Chain multiple agents for staged processing:

ingest → classify → route → specialist → review → publish

Each stage is a separate group. Use delegate_group or direct message routing. Example: support intake → triage agent → specialist teams → summary agent → publish.

Skills

MCP vs In-Context Skills

Aspect	MCP Tools	In-Context Skills
Context window	Tool name + description only	Full SKILL.md in system prompt
Authority	Host-enforced grants	Agent-enforced (prompt-based)
State	Stateless, always available	Loaded at session start, persists
Best for	Platform operations (routing, groups, tokens)	Workflow patterns, domain knowledge, multi-step procedures

Rule: Use MCP for side effects (send message, create group, issue token). Use in-context skills for knowledge and workflow guidance.

Skill Development

Each skill is a directory under ~/.claude/skills/<name>/ with:

SKILL.md — description, workflow, ALWAYS/NEVER triggers
Optional: scripts, templates, reference files

Gateway reads SKILL.md at session start, injects into system prompt. Skills compose — agent can invoke multiple skills per turn.

Skill Marketplace Patterns

(Research in progress. Placeholder for skill discovery, versioning, dependencies, and performance evals.)

Skill discovery: local index, remote registry?
Versioning: semver, lock file?
Dependencies: skill-to-skill references?
Evals: measurable performance improvements?

Performance Improvements

Measurable improvements from skill-based workflows:

Dispatch latency: ALWAYS/NEVER triggers reduce skill-matching overhead
Context efficiency: tight skill descriptions vs bloated prompts
Eval-driven iteration: A/B test skill variants, track success rate