OpenWork Server Sidecar
Relevant source files
The following files were used as context for generating this wiki page:
The OpenWork Server Sidecar is a filesystem-backed API layer that acts as a lifecycle supervisor for the OpenCode engine. It provides a stable control plane for remote clients to interact with local workspaces, managing configurations for skills, plugins, Model Context Protocol (MCP) servers, and custom commands. By decoupling the UI from the underlying engine, the sidecar allows OpenWork to function in both "Host" mode (running locally) and "Client" mode (connecting to a remote device).
This sidecar is designed with a CLI-first, Unix-like philosophy, ensuring that any infrastructure component is runnable via a single command and remains composable without special casing. It manages the active workspace context and exposes pairing endpoints, allowing remote clients—such as mobile devices—to discover and control the OpenCode engine securely.
Sources: INFRASTRUCTURE.md:1-20, packages/app/pr/openwork-orchestrator.md:4-15, ARCHITECTURE.md:44-55
Core Architecture and Lifecycle
The OpenWork Server operates as a standalone Node.js/Bun process that supervises the OpenCode engine (opencode serve). In "Host" mode, the Tauri application or the openwrk CLI spawns the server, which in turn ensures the OpenCode instance is healthy and configured for the selected workspace.
System Interaction Flow
The following diagram illustrates how the OpenWork Server sits between the Client UI and the OpenCode Engine.
The server maintains a registry of workspaces and handles the initialization of the OpenCode process with correct parameters (port, hostname, and directory).
Sources: packages/headless/src/cli.ts:741-780, ARCHITECTURE.md:44-55, packages/app/pr/openwork-orchestrator.md:20-30
Startup and Health Monitoring
Upon boot, the server generates or validates security tokens and performs health checks. It exposes a /health endpoint used by clients to verify connectivity and compatibility.
| Parameter | Source | Description |
|---|---|---|
OPENWORK_TOKEN | Env/CLI | Bearer token for client authentication. |
OPENWORK_HOST_TOKEN | Env/CLI | Token required for host-level approval of write operations. |
port | Config | Default port 8787. |
Sources: packages/server/README.md:14-25, packages/headless/src/cli.ts:80-90, packages/server/src/server.ts:75-90
Security and Authentication
The sidecar implements a two-tier authentication model to protect the host filesystem and engine state.
Authentication Modes
- Client Authentication: Remote clients must provide a
Bearertoken in theAuthorizationheader. This allows access to read operations and task submissions. - Host Authentication: Sensitive write operations (modifying
opencode.json, adding skills, or approving tool executions) require theX-OpenWork-Host-Token.
Sources: packages/server/src/server.ts:114-135, packages/server/README.md:73-78
Approval System
All destructive or configuration-altering actions are gated by an approval service. By default, the server operates in manual mode, requiring a host-side response via the /approvals API.
API Surface and Data Management
The server provides a comprehensive REST API for managing the OpenCode environment. These endpoints primarily interact with files located in the .opencode/ directory of the active workspace.
Workspace Endpoints
GET /workspaces: Lists the active workspace and its associated OpenCode connection details.POST /workspaces/:id/activate: Switches the host's active workspace.POST /workspace/:id/engine/reload: Forces the OpenCode engine to dispose of the current instance and re-read configuration.
Sources: packages/server/src/server.ts:182-205, packages/server/src/server.ts:285-300
Extension Management
The sidecar serves as the primary interface for managing OpenCode extensibility primitives.
| Module | Endpoint | Target Storage |
|---|---|---|
| Plugins | /workspace/:id/plugins | opencode.json |
| Skills | /workspace/:id/skills | .opencode/skills/<name>/SKILL.md |
| MCP | /workspace/:id/mcp | opencode.json (mcp section) |
| Commands | /workspace/:id/commands | .opencode/commands/<name>.md |
Sources: packages/server/src/server.ts:312-420, packages/server/README.md:46-68
Infrastructure and Deployment
The OpenWork Server is designed to be highly portable, shipping as a compiled binary that does not require Bun or Node.js at runtime.
Configuration Methods
Configuration is resolved through a hierarchy of sources:
- CLI Flags: Overrides all other settings (e.g.,
--port,--workspace). - Environment Variables: Useful for headless/Docker deployments (e.g.,
OPENWORK_APPROVAL_MODE). - Config File: JSON file located at
~/.config/openwork/server.json.
Sources: packages/server/README.md:14-44, packages/headless/src/cli.ts:100-140
Headless Orchestration (openwrk)
For server-side deployments, the openwrk utility acts as a headless host orchestrator. It manages the simultaneous lifecycle of the OpenCode engine, the OpenWork Server sidecar, and optional bridges like Owpenbot.
Conclusion
The OpenWork Server Sidecar is a critical supervisor component that transforms the OpenCode engine into a manageable, remote-accessible service. By providing structured API access to workspace primitives and enforcing a robust host-approval security model, it ensures that "agentic work" remains safe and auditable regardless of the client device used.