Autonomous Daemon Runtime
Relevant source files
The following files were used as context for generating this wiki page:
The Autonomous Daemon Runtime is a local execution engine designed to manage AI coding agents working through a habitat's task backlog unattended. It functions as a coordination layer that bridges the gap between structured task orchestration and raw CLI agent execution. The daemon handles the lifecycle of agent operations, including claiming pending tasks, spawning managed CLI sessions, monitoring progress via heartbeats, and implementing automated recovery from crashes or silence.
Sources: README.md:183-188, CONTEXT.md:21-30
Operating as part of an Orcy pod, the daemon provides a hands-off execution environment where humans focus on mission creation and review, while the runtime handles the tactical execution of tasks. It is designed to be agnostic, supporting multiple agent clients like Claude Code, Cursor, and Gemini CLI, and can operate in either a UI-controlled in-process mode or as a standalone background CLI process.
Sources: README.md:188-193, README.md:100-108
Core Architecture and Lifecycle
The runtime operates through a continuous poll loop that monitors specific habitats for work. When a task becomes claimable, the daemon initiates a structured lifecycle to move the task from the backlog to completion.
Task Execution Flow
The following diagram illustrates the high-level process from task detection to submission within the daemon runtime.
The daemon ensures that task transitions follow the Orcy hierarchical model (Habitat -> Mission -> Task -> Subtask).
Sources: README.md:188-191, README.md:46-51, packages/installer/skills/orcy-overview/SKILL.md:10-14
Atomic Claiming and Silence Detection
To prevent race conditions in multi-agent environments, the daemon utilizes an Atomic Claiming mechanism. This lock-free design ensures that no two agents can grab the same task simultaneously, even under concurrent access. Furthermore, the Silence Detection sub-system monitors active orcys; if an agent goes silent or stalls for more than 30 minutes, the runtime automatically releases the task back to the "hunt," allowing other pod members to claim it.
Sources: README.md:37-38, README.md:42-43, CONTEXT.md:255-260
Daemon Operations and CLI
The daemon is managed primarily through the orcy daemon command set, which allows for registration, background execution, and diagnostic checks.
| Command | Description |
|---|---|
orcy daemon detect | Scans the local environment to check which Agent CLIs (e.g., Claude Code, Codex) are installed. |
orcy daemon register | Links the daemon to a specific Orcy API URL and set of Habitat IDs. |
orcy daemon start | Initiates the background poll loop. Using --detach runs it as a persistent service. |
Sources: README.md:188-192
Managed Agent Sessions
When a task is claimed, the daemon spawns a session for a registered agent. These agents are identified by a unique agentId and authenticated via an apiKey. The identity of the agent is derived server-side from the API key to prevent impersonation.
Sources: packages/mcp/src/api.ts:167-173, packages/installer/skills/orcy-overview/SKILL.md:89-94
Execution Safety and Governance
The runtime operates under a set of quality and governance constraints known as Breach Gates. These gates ensure that work meets specific requirements before it reaches human review.
Governance Mechanisms
- Domain Routing: The daemon only assigns tasks to agents whose
requiredDomain(e.g., frontend, backend) andrequiredCapabilities(e.g., typescript, postgresql) match the agent's profile. - Dependency Blocking: Tasks with unmet dependencies (defined by
dependsOnorblocksfields) remain hidden from the daemon's poll loop to avoid wasted cycles. - Quality Checklist: Tasks may have gated completion requirements that must be validated before the daemon can successfully submit the work.
Sources: README.md:39-41, packages/installer/skills/orcy-overview/SKILL.md:47-51
Recovery and Failure Context
If a task fails during daemon execution, the system captures a Failure Context. This is a structured bundle including:
- The failure reason and kind.
- Artifacts produced before the failure.
- Agent experience signals (e.g.,
stuck,confused,backtrack). - Retry history and lifecycle events.
Sources: CONTEXT.md:300-307, packages/mcp/src/api/interfaces.ts:133-140
The sequence above details the interaction between the local daemon runtime, the spawned agent, and the central Orcy API server.
Sources: README.md:193-195, packages/mcp/src/api.ts:403-417, packages/mcp/src/api.ts:503-518
Summary
The Autonomous Daemon Runtime provides the mechanical backbone for Orcy's autonomous work execution. By managing atomic task transitions, providing robust silence detection, and enforcing domain-specific governance, it allows AI agents to operate as productive, reliable members of a pod without requiring constant human oversight of the CLI lifecycle.