Container

Packages: container/, groupfolder/, mountsec/.

Lifecycle

Each agent invocation follows this sequence:

1. EnsureRunning — verify Docker is reachable via the daemon socket
2. CleanupOrphans — stop any stale arizuko-* containers left from a previous crash
3. Resolve group path — groupfolder.Resolver maps the group folder name to an absolute host path
4. BuildMounts — assemble the volume mount list (see table below)
5. mountsec.ValidateAdditionalMounts — check extra mounts against the allowlist
6. seedSettings — write settings.json to the session's .claude/ directory: env vars, arizuko MCP server config via socat, sidecar MCP entries
7. seedSkills — copy container/skills/ to the session on first run (non-destructive; skips files that exist). Also seeds .claude.json if missing (required by Claude Code; keyed by folder for a stable userID hash)
8. StartSidecars — launch any per-group MCP sidecar containers (docker run -d)
9. docker run -i --rm — start the agent container, write input JSON to stdin
10. Stream output — read stdout, scan for delimiter markers, capture output JSON
11. Timer-based timeout — graceful docker stop then Process.Kill if exceeded
12. StopSidecars — stop and remove sidecar containers after agent exits

Container run logs are written to groups/<folder>/logs/container-<timestamp>.log.

Volume mounts

Host path	Container path	Mode	Purpose
groups/<folder>/	/workspace/	rw	Group working directory ($HOME)
groups/<world>/share/	/workspace/share/	rw	Cross-group shared state within a world
data/sessions/<folder>/	/root/	rw	Agent session state (.claude/ dir)
data/ipc/<folder>/	/var/run/pub/arizuko/	rw	MCP unix sockets
container/skills/	/skills/	ro	Skill CLAUDE.md files (read by agent)
groups/<folder>/media/	/workspace/media/	rw	Received media files
web/ (optional)	/workspace/web/	ro	Web assets (when web channel active)
extra mounts	/workspace/extra/<name>/	rw or ro	Additional mounts from container_config

Input JSON schema

Written to the container's stdin as a single JSON line:

{
  "sessionId":     "session ID or empty for new session",
  "messages":      [ { "role": "...", "content": "..." } ],
  "systemPrompt":  "prepended XML blocks (diary, episodes, grants, etc.)",
  "grants":        [ "rule1", "rule2" ],
  "folder":        "group folder name",
  "senderJid":     "JID of the originating sender"
}

Output protocol

The container writes all output to stdout. The gateway ignores all lines until it sees the start marker, then captures until the end marker:

---ARIZUKO_OUTPUT_START---
{"status":"ok","result":"agent reply text","newSessionId":"...","error":""}
---ARIZUKO_OUTPUT_END---

During the run, the gateway polls the IPC socket for tool call results and pipes responses back via stdin. A _close sentinel on the IPC input channel signals the container to flush and exit.

Status values: ok (success, cursor advances), error (failure with output, cursor advances), fatal (no output, cursor rolls back).

Container naming

• Regular invocations: arizuko-<folder>-<timestamp_ms>
• Isolated scheduler tasks: arizuko-<folder>-task-<task_id> (sender: scheduler-isolated:<task_id>)

seedSettings

seedSettings writes settings.json into the session's .claude/ directory before each invocation. It contains:

• Environment variable overrides for the agent
• The arizuko MCP server entry pointing to socat UNIX-CONNECT:/var/run/pub/arizuko/router.sock
• One MCP entry per configured sidecar, each using its own socat path

seedSkills

seedSkills runs once per group (non-destructive). It copies the bundled container/skills/ tree into the session's .claude/skills/ directory. Files are skipped if they already exist, so operator customizations are preserved.

Skills versioning: the bundled skills carry a MIGRATION_VERSION file. On startup, the gateway compares the installed version against the bundled one. If the bundled version is higher, it applies the numbered migration files (NNN-desc.md) in order, which may overwrite specific skill files.

Sidecars

Per-group MCP sidecars are defined in GroupConfig.Sidecars. For each sidecar:

1. StartSidecars runs docker run -d with the sidecar image, socket volume at ipc/sidecars/<name>.sock, memory limit, and CPU limit
2. The socket path is wired into settings.json as an additional mcpServers entry
3. StopSidecars calls docker stop then docker rm -f after the agent container exits

Security flags

--cap-drop ALL
--security-opt no-new-privileges
--memory 1g
--cpus 2
--network none          (default; overridable per group)
--read-only             (root filesystem; writable mounts are explicit)

Mount security

Package: mountsec/. Additional mounts from container_config are validated against ~/.config/pub/arizuko/mount-allowlist.json before the container starts:

• Path must be absolute and exist on host
• Symlinks are resolved before comparison
• Path must be under a configured AllowedRoot
• Blocked patterns: .ssh, .gnupg, .env, credential files, private keys
• Non-root groups forced read-only when NonMainReadOnly is configured

Docker-in-Docker path translation

When the gateway itself runs inside Docker, container.hp() translates local paths to host-side paths. HOST_DATA_DIR provides the host-side base; HOST_APP_DIR maps the application directory. Volume mounts passed to docker run use the translated paths so the inner Docker daemon can resolve them.