Openwrk CLI & Daemon
Relevant source files
The following files were used as context for generating this wiki page:
Openwrk is the headless host orchestrator for the OpenWork ecosystem, serving as a CLI-first alternative to the desktop application. It acts as a lifecycle supervisor that manages the execution and coordination of the OpenCode engine, the OpenWork server, and optional sidecars like Owpenbot. By providing a stable local control plane, it allows developers and power users to run agentic workflows without the need for a graphical user interface.
The system is designed around a "sidecar-composable" architecture, ensuring that every infrastructure component remains runnable via a single CLI command. This approach supports a multi-workspace router daemon that keeps a single OpenCode process alive while switching project contexts Just-In-Time (JIT) based on directory parameters.
Sources: packages/headless/README.md:1-5, INFRASTRUCTURE.md:1-15, packages/app/pr/openwrk-multi-workspace.md:5-12
System Architecture
Openwrk operates as a central router and supervisor. It manages a workspace registry and coordinates the lifecycle of various sub-processes. The architecture prioritizes "CLI-first" and "Unix-like interfaces," utilizing JSON over stdout and environment variables for configuration.
Core Components
- Openwrk CLI/Orchestrator: The main entry point that manages process spawning, health checks, and binary integrity verification via SHA-256 manifests.
- Router Daemon: A local-only control plane that maintains a persistent
opencode serveprocess and routes requests to specific workspace instances. - OpenCode Engine: The underlying execution engine that performs the actual agentic tasks.
- OpenWork Server: A filesystem-backed API that provides remote clients with access to skills, plugins, and commands.
Sources: packages/headless/src/cli.ts:15-35, packages/headless/README.md:10-15, INFRASTRUCTURE.md:46-56
Component Relationship Diagram
The following diagram illustrates how the Openwrk CLI orchestrates the various services and sidecars.
The Openwrk CLI serves as the supervisor, spawning the Daemon and sidecars which then interact with the OpenCode engine and filesystem-backed registries.
Sources: packages/headless/src/cli.ts:890-950, packages/app/pr/openwrk-multi-workspace.md:25-45
Router Daemon & Multi-Workspace Management
The router daemon is a critical feature for performance and resilience. Instead of restarting the entire engine when a workspace changes, the daemon keeps one OpenCode process running and switches context using the directory parameter.
JIT Lifecycle and Routing
Instances are created or reused Just-In-Time when a request is made for a specific workspace. The daemon tracks last-used timestamps to support future idle eviction and isolation.
State Persistence
The daemon maintains a state file (openwrk-state.json) which includes:
- PIDs for the daemon and opencode processes.
- The
activeIdof the currently selected workspace. - A list of registered
workspaces(both local and remote).
Sources: packages/headless/src/cli.ts:1001-1040, packages/app/pr/openwrk-multi-workspace.md:38-42, packages/app/pr/openwrk-multi-workspace.md:76-105
Data Model: Workspace Registry
| Field | Type | Description |
|---|---|---|
id | string | Stable ID derived from path or URL hash |
name | string | Friendly name for the workspace |
path | string | Normalized local filesystem path |
workspaceType | "local" | "remote" | Indicates if workspace is local or a remote host |
baseUrl | string | (Remote only) Connection URL for the host |
directory | string | (Remote only) Target directory on the remote host |
Sources: packages/headless/src/cli.ts:40-52, packages/app/pr/openwrk-multi-workspace.md:76-105
CLI Commands Reference
Openwrk provides a comprehensive command set for process management and workspace interaction.
Execution Control
| Command | Description |
|---|---|
start | Starts OpenCode + OpenWork server + Owpenbot |
daemon run | Runs the router daemon in the foreground |
daemon start | Starts the router daemon in the background |
daemon stop | Stops the running daemon and its sub-processes |
status | Reports health of OpenCode and OpenWork server |
Sources: packages/headless/README.md:23-26, packages/headless/src/cli.ts:770-800
Workspace Management
- Add Local:
openwrk workspace add /path/to/workspace - Add Remote:
openwrk workspace add-remote <baseUrl> --directory <path> - List:
openwrk workspace list --json - Switch:
openwrk workspace switch <id> - Dispose:
openwrk instance dispose <id>(terminates a specific workspace instance)
Sources: packages/headless/README.md:28-34, packages/headless/src/cli.ts:805-835
Configuration and Environment
Openwrk can be configured via CLI flags or environment variables. CLI flags take precedence.
| Flag | Env Variable | Default |
|---|---|---|
--workspace | OPENWORK_WORKSPACE | process.cwd() |
--openwork-port | OPENWORK_PORT | 8787 |
--approval | OPENWORK_APPROVAL_MODE | manual |
--data-dir | OPENWRK_DATA_DIR | ~/.openwork/openwrk |
--allow-external | OPENWRK_ALLOW_EXTERNAL | false |
Sources: packages/headless/src/cli.ts:890-930, packages/server/README.md:22-35
Binary Verification Logic
Openwrk enforces security by validating bundled binaries before execution.
async function verifyBinary(path: string, expected?: VersionInfo): Promise<void> {
if (!expected) return;
const hash = await sha256File(path);
if (hash !== expected.sha256) {
throw new Error(`Integrity check failed for ${path}`);
}
}
Sources: packages/headless/src/cli.ts:316-322
Interaction Flow: Approvals
When running in manual approval mode, writes are gated. The CLI provides commands to interact with the OpenWork server's approval system.
Approval Sequence Diagram
The following sequence shows how a user interacts with a pending permission request via the CLI.
Openwrk serves as a robust foundation for automated agentic environments, providing the necessary tools to manage complex workspace setups and process lifecycles through a standard terminal interface.