Runtime layout

The runtime root holds global configuration, agent content and state, plugin packages, logs, and OAuth credentials.

init creates the runtime root, the global config/ directory, and the agents/ directory.

Global configuration

config/ holds runtime-wide settings and state.

• system.toml — optional global timezone and [updater] repository settings; see Upgrades.
• plugins.toml — the plugin list.
• remote.toml — optional TLS remote listener and discovery settings; see Remote sessions.
• plugins/<name>.toml — per-plugin configuration.
• openai-codex/ — OpenAI Codex OAuth credentials, one file per auth id.
• migrations.json — applied configuration migration state.
• backups/<migrationId>/ — immutable backups of files changed by migrations.

Host-level state/remote.db stores remote grants, invitation and credential verifiers, session ownership, submissions, outputs, and recovery receipts separately from conversation history. Its private local operator socket and authority lock also live under state/. Back up remote authority state together with agent session databases.

Agents

Agents live below agents/<slug>/; each agent owns its instructions, memory blocks, skills, task files, and channel configuration.

• core.md — required base instructions.
• blocks/ — required memory blocks (soul.md, identity.md, person.md, long-term.md, style-notes.md) plus optional conditional/*.md blocks.
• config/engine.toml — required inference provider configuration.
• config/tools.toml — required tool enablement.
• config/mcp.toml — optional per-agent Streamable HTTP MCP servers; see HTTP MCP tools.
• config/sandbox.toml — optional command-execution sandbox configuration.
• config/conditions.toml — optional conditional block and path access rules.
• config/heartbeat.toml — optional heartbeat configuration.
• config/cron.toml — optional scheduled jobs.
• config/channels/discord.toml — optional Discord integration.
• config/plugins/<name>.toml — per-agent plugin configuration.
• memories/ — agent memory files.
• skills/<slug>/SKILL.md — reusable skill documents.
• tasks/ — scheduled task files, including HEARTBEAT.md.
• workspace/ — the agent's working area.
• state/<plugin-slug>/ — persistent plugin state.
• sessions.db — the agent's SQLite session database.
• media/ — persisted image and video data referenced by sessions.

On startup, the runtime migrates the legacy images/ directory and its session index to media/.

• discord-commands.hash — registered Discord command fingerprint.
• discord-presence.json — persisted desired Discord status and custom status message.

Startup

Agents are composed concurrently, allowing configuration reads and gateway handshakes to overlap. Startup reads each agent's lightweight session index but does not restore session histories or media as part of that index load. The runtime hydrates a persisted session when a channel, scheduler, target resolution, or session operation first uses it. Discord gateway handshakes can dominate startup time, but their latency depends on external services.

Configuration migration and plugin loading stay sequential and complete before any agent starts. Each agent initializes its own configured HTTP MCP connections and discovers tools during composition. Startup still includes shared preparation and per-agent work; elapsed time depends on agent count, available resources, and external services. Log lines from different agents interleave during startup; each line still names its agent.

If one agent has invalid configuration, the whole startup fails and no agent is left running. Fix the reported file and start again.

Logs

Runtime logs are written under logs/ as daily rolling JSON files.

Configuration

Configuration is TOML-only.

Use cireilclaw dry-run to validate startup configuration without starting the host or writing runtime state. When MCP servers are configured, validation contacts them to initialize connections and discover tool definitions, but does not invoke tools.

Live reload

The running runtime watches agent configuration files and the global config/system.toml file. Changes to system.toml timezone settings apply to subsequent turns and Discord-rendered timestamps. Changes to plugins.toml, plugin code, channels/discord.toml, mcp.toml, or remote.toml still require a full runtime restart.