Orchestrator CLI
Relevant source files
The following files were used as context for generating this wiki page:
The Orchestrator CLI is a core component of the OpenWork ecosystem designed to manage and coordinate local host stacks. It serves as a headless alternative to the desktop application, allowing users to run agentic workflows, skills, and Model Context Protocol (MCP) servers directly from the command line. It orchestrates the lifecycle of several key services: opencode, openwork-server, and opencode-router.
Sources: README.md:15-18, apps/orchestrator/package.json:3-4
The primary purpose of the Orchestrator is to provide a practical control surface for agentic work that is local-first but cloud-ready. It allows for the composition of server surfaces and messaging connectors (like Slack or Telegram) without vendor lock-in, treating the OpenWork application essentially as a client of the server API surface managed by the Orchestrator.
Sources: AGENTS.md:5-15, README.md:105-108
Architecture and Components
The Orchestrator operates in Host mode, where it manages a local execution stack. It is responsible for initiating the OpenWork server and the OpenCode engine, which together handle session management, prompt execution, and tool orchestration.
Sources: README.md:105-112
Service Orchestration
The CLI manages the following dependencies and services:
- OpenWork Server: A Bun-based server that hosts approvals, audit logs, and manages the OpenCode lifecycle.
- OpenCode Engine: The local runtime for agents, tools, and model providers.
- OpenCode Router: An optional component for routing requests between different engine instances.
Sources: apps/orchestrator/package.json:44-48, README.md:108-110
Orchestration Flow
The following diagram illustrates how the Orchestrator initializes the local environment:
The Orchestrator acts as the parent process that ensures the server and engine are correctly configured and communicating.
Sources: README.md:105-115, packaging/docker/docker-compose.dev.yml:45-75
CLI Usage and Configuration
The Orchestrator can be installed globally and run with various flags to customize the local environment, such as specifying workspace paths and approval modes.
Sources: README.md:16-18
Commands and Flags
| Command/Flag | Description | Default/Example |
|---|---|---|
openwork start | Starts the orchestrator services. | — |
--workspace | Defines the path to the project workspace. | /path/to/workspace |
--approval | Sets the permission request mode. | auto or manual |
--openwork-port | Port for the OpenWork server. | 8787 |
--remote-access | Enables sharing the instance over the network. | — |
--cors | Configures allowed origins for the API. | * |
Sources: README.md:18, packaging/docker/docker-compose.dev.yml:68-77
Environment Variables
The Orchestrator recognizes several environment variables for configuration, particularly when running in containerized or development environments.
Sources: packaging/docker/docker-compose.dev.yml:10-21
| Variable | Description |
|---|---|
OPENWORK_TOKEN | Shared client token for authentication. |
OPENWORK_HOST_TOKEN | Admin token for host-level operations/approvals. |
OPENWORK_DEV_MODE | Enables isolated OpenCode state for development. |
OPENWORK_SERVER_BIN | Path to the server entry point (e.g., src/cli.ts). |
Sources: packaging/docker/docker-compose.dev.yml:58-65, apps/orchestrator/package.json:8
Core Functionality
Session and Tool Management
The Orchestrator exposes APIs via the openwork-server to perform the following:
- Session Lifecycle: Creating and deleting sessions and listing previous message history.
- Prompting: Sending prompts asynchronously and receiving real-time updates via Server-Sent Events (SSE).
- Skill Discovery: Managing folders under
.opencode/skills/and making them available to agents. - Artifact Handling: Resolving, reading, and writing files produced by agents (e.g., CSV, Markdown, XLSX).
Sources: README.md:37-51, apps/server/src/artifact-files.e2e.test.ts:46-65
Permission and Approval System
One of the critical roles of the Orchestrator is to surface permission requests from the OpenCode engine to the user. This includes shell command execution, file modifications, and external directory access. These can be approved via the CLI or connected UIs.
Sources: README.md:44-45, apps/server/src/artifact-files.e2e.test.ts:25-30
This flow ensures that agents operate within user-defined guardrails.
Sources: README.md:112-115, apps/server/src/artifact-files.e2e.test.ts:25-30
Development and Testing
The orchestrator package includes scripts for building binaries across multiple platforms and running end-to-end tests for specific features like routing and file handling.
Sources: apps/orchestrator/package.json:7-15
Build Targets
The Orchestrator can be compiled for several architectures using Bun:
bun-darwin-arm64/bun-darwin-x64bun-linux-x64/bun-linux-arm64bun-windows-x64
Sources: apps/orchestrator/package.json:10-11
Testing Infrastructure
Testing the Orchestrator often involves spawning mock servers or using the provided test suites:
test:router: Validates theopencode-routerlogic.test:files: Validates file session handling.artifact-files.e2e.test.ts: Tests the full flow of starting a server, resolving artifacts, and performing authenticated file operations.
Sources: apps/orchestrator/package.json:14-15, apps/server/src/artifact-files.e2e.test.ts:38-44
Summary
The Orchestrator CLI is the foundational service coordinator for OpenWork. By managing the OpenCode engine and OpenWork server, it provides an "ejectable" and composable environment for agentic automation. It facilitates local execution with enterprise-grade features like audit logs, permissioning, and artifact management, making it suitable for both individual developers and integrated team workflows.