OpenWork Local Server
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork Local Server is a filesystem-backed API layer designed to provide a control surface for agentic workflows. It serves as an open-source alternative to Claude Cowork/Codex, enabling users to run OpenCode agents, skills, and Model Context Protocol (MCP) servers locally on their machines or on remote servers. The server acts as the primary interface for the OpenWork desktop application and other clients (like WhatsApp or Slack connectors), facilitating local-first automation while remaining cloud-ready.
The server orchestrates core components including opencode, openwork-server, and optionally opencode-router. It manages workspace initialization, handles real-time updates via Server-Sent Events (SSE), and gates privileged operations through a manual or automated approval system.
Sources: README.md:1-15, apps/server/README.md:1-5, AGENTS.md:1-10
Architecture and Components
The OpenWork ecosystem utilizes a multi-process architecture where the local server coordinates between the user interface and the underlying execution engines.
Orchestration Layer
The server is typically managed by the OpenWork Orchestrator, which handles the lifecycle of various sidecar processes. These include:
- OpenCode: The primary execution engine for agentic tasks.
- OpenWork Server: The API layer providing filesystem access and session management.
- OpenCode Router: An optional daemon for managing multiple workspaces simultaneously.
Sources: apps/orchestrator/README.md:1-15, README.md:88-95
Process Flow
The following diagram illustrates the interaction between the Orchestrator, the Server, and the OpenCode engine during a typical session.
The diagram shows how the Orchestrator manages sidecar processes and how the Server interfaces with the UI and Workspace.
Sources: apps/orchestrator/README.md:40-60, README.md:105-115
Workspace Management
The server provides comprehensive APIs for managing local project folders, referred to as workspaces.
Initialization Logic
When a directory is selected as a workspace, the server performs an initialization routine via ensureWorkspaceFiles. This ensures that required configuration files and agent definitions exist:
- opencode.jsonc: Main configuration for tools and plugins.
- openwork.json: Metadata about the workspace, including its preset (e.g., "starter").
- openwork.md: The default agent definition which includes specific instructions for browser control and artifact handling.
Sources: apps/server/src/workspace-init.ts:100-140
Workspace Configuration Fields
| Field | Type | Description |
|---|---|---|
version | number | Schema version (default: 1). |
workspace.name | string | Display name derived from the folder basename. |
workspace.preset | string | Workspace template (default: "starter"). |
authorizedRoots | string[] | List of filesystem paths the workspace can access. |
Sources: apps/server/src/workspace-init.ts:80-95
API Surface and Endpoints
The server exposes several categories of endpoints to facilitate remote client interaction and local automation.
Core Endpoints
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Basic server health check. |
/status | GET | Current server and engine status. |
/workspaces | GET | List available workspaces. |
/workspace/:id/events | GET | SSE stream for real-time updates. |
/workspace/:id/engine/reload | POST | Restarts the underlying OpenCode engine. |
Sources: apps/server/README.md:50-75
Filesystem and Artifacts
The server supports "Artifacts"—standardized output files like Markdown, CSV, and HTML that the UI can preview.
- Artifact Resolution: The
POST /workspace/:id/artifacts/resolveendpoint checks for the existence of files and suggests preview types (e.g., "sheet" for CSV/XLSX, "markdown" for MD). - Batch Operations: Support for batch reading and writing of files through session-based APIs.
Sources: apps/server/src/artifact-files.e2e.test.ts:50-85, apps/server/README.md:100-115
Security and Approvals
Security is maintained through a token-based authentication system and an approval gateway for sensitive operations.
Authentication
The server uses three distinct tokens:
- Client Token: Used by remote clients for general API access.
- Host Token: A high-privilege token for administrative actions and approvals.
- Owner Token: A scoped token that can answer permission prompts.
Sources: apps/server/README.md:120-135
Approval Modes
The server can operate in two approval modes, configured via OPENWORK_APPROVAL_MODE:
- Manual: Privileged operations (like shell commands or file writes) are queued and require an explicit reply via the
/approvals/:idendpoint. - Auto: Operations are automatically approved, intended for trusted local development environments.
Sequence diagram showing the manual approval flow for privileged agent actions.
Sources: apps/server/README.md:130-145, README.md:100-105
Configuration Options
Server behavior can be customized using environment variables or a JSON configuration file (defaulting to ~/.config/openwork/server.json).
| Variable | Description | Default |
|---|---|---|
OPENWORK_PORT | Port for the server to bind to. | 8787 |
OPENWORK_HOST | Host address (e.g., 127.0.0.1). | 127.0.0.1 |
OPENWORK_INBOX_ENABLED | Enables file uploads into the workspace inbox. | 0 |
OPENWORK_SANDBOX_BACKEND | Configures the sandbox (docker, container, or none). | none |
Sources: apps/server/README.md:25-45, apps/orchestrator/README.md:70-85
Summary
The OpenWork Local Server provides a robust, local-first foundation for agentic work. By orchestrating OpenCode and managing workspaces through a permissioned API, it bridges the gap between low-level terminal tools and a productized user experience. Its architecture emphasizes auditability through logs and safety through a configurable approval system, making it suitable for both individual developers and enterprise teams.
Sources: AGENTS.md:5-15, README.md:30-45