# 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](../operations/upgrades.md#using-the-published-updater). - `plugins.toml` — the plugin list. - `remote.toml` — optional TLS remote listener and discovery settings; see [Remote sessions](../operations/remote-sessions.md). - `plugins/.toml` — per-plugin configuration. - `openai-codex/` — OpenAI Codex OAuth credentials, one file per auth id. - `migrations.json` — applied configuration migration state. - `backups//` — 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//`; 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/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/.toml` — per-agent plugin configuration. - `memories/` — agent memory files. - `skills//SKILL.md` — reusable skill documents. - `tasks/` — scheduled task files, including `HEARTBEAT.md`. - `workspace/` — the agent's working area. - `state//` — 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. 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. ## 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`, or `remote.toml` still require a full runtime restart.