Docker-first coordination for long-running agents

Suzumio

Suzumio coordinates multi-agent projects with a non-preemptive mailbox scheduler, isolated Docker turns, audited tools, artifact tracking, SQLite state, a CLI, an HTTP API, and a lightweight WebUI.

Run the demo Write a config Use the API

Purpose

Suzumio is a coordination runtime for projects where agents may need to work for a long time without being interrupted. It is suitable for formalization, code work, research workflows, review pipelines, benchmark experiments, and other tasks where progress is best represented as durable turns, messages, artifacts, and audit logs.

Suzumio separates project coordination from agent execution. The core runtime owns project state and scheduling. The Docker runner executes one agent turn, calls back to Suzumio for tools, writes a result, and exits.

Non-preemptive scheduling

Running agents are not prompted, nudged, or interrupted. New inbound messages wait in the mailbox until the current turn finishes.

Durable project state

Projects store resolved configuration, agents, messages, message reads, turns, events, tool calls, and artifacts in SQLite.

Docker-first execution

Each turn runs in a container with a turn input file, an output file, an agent workspace, and ToolHost access.

Audited tools

Project tools are checked against each agent allowlist and recorded before and after execution.

What You Can Do Today

Task	Where to start	What you get
Run a local smoke test	Quickstart	A Docker-backed mock turn that verifies scheduling, storage, and runner wiring.
Define a project	Configuration	YAML config with whole-field imports, profile composition, agents, tools, and backend settings.
Operate projects from terminal	CLI Reference	Commands for init, serve, start, send, inspect, approve, and stop.
Integrate with other systems	HTTP API	Project objects, user actions, event streams, and ToolHost calls.
Deploy docs or inspect architecture	Architecture	Clear boundaries between core runtime, Docker backend, runner, ToolHost, and SQLite.

Core Workflow

1. Render and validate project config.
2. Initialize a project under SUZUMIO_ROOT.
3. Start the HTTP server and scheduler loop.
4. Send a user message to an agent.
5. Scheduler starts one Docker turn for that agent.
6. Runner executes the turn and calls ToolHost when needed.
7. Suzumio records messages, tool calls, events, artifacts, and turn output.
8. Idle agents remain quiet until new inbound messages arrive.

Project Layout

$SUZUMIO_ROOT/demo/
  suzumio.sqlite      durable project database
  source.yaml         original project config
  resolved.yaml       fully resolved config
  agents/             per-agent workspaces
  artifacts/          published files
  turns/              turn input/output directories
  logs/               reserved for runtime logs

Public Documentation Scope

This site documents the runtime contract, user workflows, configuration, CLI, API, and operational behavior. It intentionally avoids internal development history and private deployment details. Examples use placeholders for provider endpoints and keys.