Deployment & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Deployment and configuration of Orcy involve setting up a task orchestration environment that supports both human and AI coding agents. The system is designed to be agnostic regarding models and agent clients, allowing for flexible deployment across Linux and macOS platforms. Configuration is primarily driven by environment variables that manage security postures, database migrations, and agent identity.
Orcy operates in two primary security postures: local-dev for local development and remote for production-like environments. Deployment includes setting up an API server, a web UI, and various MCP (Model Context Protocol) tools to enable agentic workflows.
Sources: README.md:1-55, packages/api/src/test/documentationValidation.test.ts:20-25, packages/installer/skills/orcy-overview/SKILL.md:68-80
Quick Start & Installation
Orcy provides a one-line production installer and an interactive wizard for rapid setup. The installation process establishes the monorepo structure and configures the necessary environment for the Fastify API server and React UI.
curl -fsSL https://raw.githubusercontent.com/waterworkshq/orcy/main/install.sh | bash
orcy serve start
Installation Components
The project structure supports a modular deployment of services:
- API Server: Fastify-based backend handling orchestration logic.
- Web UI: React 19 interface for human supervision.
- Daemon: Autonomous runtime for background task execution.
- MCP Server: Protocol implementation for AI agent integration.
Sources: README.md:148-152, README.md:252-270, CONTRIBUTING.md:41-48
Security Postures & Authentication
Orcy utilizes a dual-posture security model. In a remote posture, strict validation of secrets is required to protect against unauthorized access and SSRF (Server-Side Request Forgery).
Authentication Logic
Agent identity is strictly derived from the ORCY_API_KEY. The server ignores agent ID fields in request bodies to prevent impersonation. All non-public endpoints require authentication via either API keys (for agents) or JWT (for humans).
The diagram shows how agent identity is securely bound to the API key, preventing ID spoofing in the request body.
Sources: packages/api/src/test/documentationValidation.test.ts:20-40, packages/installer/skills/orcy-overview/SKILL.md:78-85, packages/api/src/test/documentationValidation.test.ts:110-120
Configuration Environment Variables
| Variable | Description | Security Posture |
|---|---|---|
ORCY_API_URL | Base URL for the Orcy API server. | All |
JWT_SECRET | Secret for signing human session tokens. | Remote (Required) |
ORCY_REGISTRATION_TOKEN | Token required for initial agent registration. | Remote (Required) |
ORCY_SSRF_ALLOWLIST | List of allowed outbound URLs to prevent SSRF. | Remote |
ORCY_API_KEY | Scoped key for agent authentication. | All |
NODE_ENV | Environment classification (development/production). | All |
Sources: packages/api/src/test/documentationValidation.test.ts:60-95, packages/installer/skills/orcy-overview/SKILL.md:68-75
Database Initialization & Migrations
Orcy uses Drizzle ORM with a SQLite backend. The system maintains a "Production Migration Chain" to ensure data preservation during upgrades from legacy versions (e.g., v0.29).
Migration Architecture
The system employs a frozen consolidated baseline (0000_schema.sql) followed by a journal of incremental updates. During startup, the API server automatically runs the migration journal.
This flow illustrates the initialization path for both fresh installs and legacy database upgrades.
Sources: packages/api/src/test/productionMigrationChain.test.ts:1-35, CONTRIBUTING.md:270-300
Migration Verification
Orcy includes specific markers for prerelease reconciliation (e.g., the 0053 marker for plugin quarantine safety). This ensures that even if the system crashed during a prior upgrade, it can recover preserved data from temporary backup tables like __f2_quarantine_preserve.
Sources: packages/api/src/test/productionMigrationChain.test.ts:210-250
Daemon & Autonomous Mode
Deployment can include a standalone CLI daemon for persisted credentials and multi-machine operation. This daemon polls for tasks, manages worktrees, and spawns agent sessions.
Daemon Configuration
Daemons are registered via the CLI to manage specific habitats:
orcy daemon register --api-url http://localhost:4000 --habitat-ids <id1,id2>
orcy daemon start --detach
Sources: README.md:155-165, packages/installer/skills/orcy-overview/SKILL.md:95-105
Integration Setup
Orcy acts as a coordination hub for external trackers and code repositories. Integration configuration is handled via OAuth device flows or specific API tokens.
Supported External Integrations
- Issue Trackers: GitHub Issues (OAuth), Linear (OAuth PKCE), Jira Cloud (API Token).
- Code Evidence: GitHub and GitLab (linking PRs, commits, and pipeline runs via webhooks).
- Chat: Slack and Discord (pluggable notification surfaces).
Sources: README.md:175-210
The deployment of Orcy requires careful management of environment variables to maintain security, especially in remote postures. By utilizing the built-in migration chain and automated installer, Orcy ensures a stable coordination layer for both human pod members and autonomous AI agents.