Quickstart

Run the runtime end to end

This guide runs a mock agent turn in Docker. It does not require a model API key, and it verifies the core path: config, SQLite, scheduler, Docker backend, runner, HTTP API, and WebUI.

Prerequisites

Requirement	Why it is needed	Check
Node.js 24+	CLI, server, runner build, built-in SQLite module.	`node --version`
npm	Install TypeScript and runtime dependencies.	`npm --version`
Docker	Every agent turn runs in a container.	`docker ps`
Git	Clone repository and manage local changes.	`git --version`

1. Clone and Build

git clone git@github.com:OmegaCombinator/suzumio.git
cd suzumio
npm install
npm run build

2. Build the Runner Image

docker build -t suzumio-runner:dev .

The example configs use suzumio-runner:dev. If you use a different tag, set backend.image in the project config.

3. Choose a Runtime Root

export SUZUMIO_ROOT=/tmp/suzumio-root
mkdir -p "$SUZUMIO_ROOT"

SUZUMIO_ROOT stores project databases, turn files, workspaces, and artifacts. Keep it outside the Git repository.

4. Inspect the Config

suzumio config render examples/demo.yaml

Rendering config before running is recommended. It shows imported content, default values, and the final shape stored in SQLite.

5. Initialize the Project

suzumio init examples/demo.yaml
suzumio status demo

After initialization, the project is not scheduled yet. Start it explicitly when the server is running.

6. Start the Server

suzumio serve --host 0.0.0.0 --port 39400

This starts the HTTP API, ToolHost, WebUI, SSE stream, and scheduler loop. Open http://127.0.0.1:39400 in a browser.

7. Send the First Message

Open another terminal with the same SUZUMIO_ROOT.

export SUZUMIO_ROOT=/tmp/suzumio-root
suzumio start demo
suzumio send demo pm P1 "Start the mock demo and report status."

The scheduler will see an unread message for pm, create one turn, and start one Docker container.

8. Inspect Results

suzumio turns demo --limit 5
suzumio messages demo --limit 10
suzumio events demo --limit 20

A successful mock run shows a completed turn with text similar to:

Mock turn completed for pm.

This container runner is wired correctly. In AI mode, the same runner calls the configured model and Suzumio ToolHost.

9. Verify Non-preemptive Behavior

If an agent is already running, sending another message does not interrupt the current turn. The new message remains unread until the current turn completes. This is the expected default behavior.

10. Optional AI Runner Test

examples/ai-demo.yaml is sanitized. Copy it to a local untracked file before adding private endpoints.

cp examples/ai-demo.yaml /tmp/suzumio-ai-demo.yaml
# edit /tmp/suzumio-ai-demo.yaml locally
export SUZUMIO_GATEWAY_API_KEY=...
suzumio init /tmp/suzumio-ai-demo.yaml

Do not commit real API keys, private gateway URLs, or private provider names. Keep them in local config and environment variables.

Troubleshooting

Symptom	Cause	Action
Turn fails before writing output.	Runner image not built, wrong image name, or container startup failure.	Run `docker build -t suzumio-runner:dev .` and inspect `docker logs <container>`.
Tool call connection refused.	Container cannot reach Suzumio server.	Run server with `--host 0.0.0.0` and use `http://host.docker.internal:39400`.
Agent does not start.	Project is not `running` or agent has no unread inbound message.	Run `suzumio start project` and send a direct message to the agent.
GitHub Pages custom domain is HTTP only.	Certificate is still provisioning.	Wait for GitHub Pages certificate issuance, then enable HTTPS enforcement.