openwork-server: The OpenWork Backend Service Explained

The openwork-server is a standalone HTTP backend that transforms local workspaces into secure, remotely accessible APIs, handling filesystem operations, OpenCode proxying, and token-based authentication for the OpenWork ecosystem.

The openwork-server serves as the central nervous system of the OpenWork project, bridging local directories with remote clients through a RESTful interface. As part of the different-ai/openwork repository, this backend component enables desktop applications, headless web UIs, and CLI tools to interact with workspace content programmatically while enforcing strict security boundaries.

Core Architecture and Responsibilities

The openwork-server operates as a standalone HTTP service that consolidates multiple critical backend functions. According to the implementation in apps/server/src/server.ts, the server exposes health, status, and capability endpoints alongside its primary API surface, enabling client discovery and runtime monitoring.

Filesystem-Backed API Operations

At its foundation, the server provides a filesystem-backed API that allows remote clients to read and modify workspaces, plugins, skills, MCPs (Model Context Protocols), commands, and files. This architecture enables real-time collaboration across different interfaces while maintaining data persistence on the host machine. Clients can list workspaces, inspect directory structures, and execute file operations without requiring direct filesystem access on the host.

OpenCode Engine Gateway

The server acts as the gateway to the OpenCode engine, proxying any /opencode/* request to the embedded OpenCode instance. As implemented in the routing layer, this proxy functionality validates client tokens and enforces permission checks before forwarding traffic, ensuring that OpenCode operations respect the same security boundaries as native OpenWork API calls.

Security Model and Access Control

Security in the openwork-server relies on a token-based authentication system with distinct privilege levels and host-gated approvals for all write operations.

Host-Level Approvals

The apps/server/src/approvals.ts file implements the host-level approval service that gates write operations. Before modifying workspace content, the server requires explicit approval based on the configured approval mode—ranging from automatic acceptance in development environments to strict manual confirmation for production deployments.

Token Generation and Validation

The apps/server/src/tokens.ts module handles token generation and validation, supporting three access tiers:

• Owner: Full administrative control over workspace configuration and user management
• Collaborator: Read and write capabilities for workspace content
• Viewer: Read-only access to files and metadata

When launching the server, it automatically generates and logs both client and host tokens, making initial setup straightforward while maintaining clear security boundaries between different access levels.

Deployment and Configuration

The openwork-server supports both local development and production environments through environment-driven configuration and flexible deployment options.

Quick Start with NPM

Install and run the pre-built binary globally:

npm install -g openwork-server
openwork-server --workspace /path/to/my/workspace --approval auto

The --approval auto flag configures automatic approval for write operations, suitable for development environments. The server logs autogenerated tokens on startup for immediate client configuration.

Development Mode from Source

When working with the repository directly, run the server using pnpm:

pnpm --filter openwork-server dev -- \
  --workspace /path/to/my/workspace \
  --approval auto

Add --verbose to view resolved configuration details and routing information during development.

HTTP API Usage

Once running, interact with the API using standard HTTP requests. List available workspaces with:

curl -H "Authorization: Bearer $OPENWORK_TOKEN" http://127.0.0.1:8787/workspaces

The response includes workspace metadata such as ID, name, base URL, and filesystem path:

{
  "workspaces": [
    {
      "id": "finance",
      "name": "Finance",
      "baseUrl": "http://127.0.0.1:4096",
      "path": "/Users/susan/Finance"
    }
  ]
}

OpenCode Proxy Example

Access the embedded OpenCode engine through the proxy endpoint:

curl http://127.0.0.1:8787/opencode/v1/agents

The server validates the token scope before forwarding the request to the OpenCode instance, returning the engine's response unchanged to the client.

Advanced Capabilities

Beyond basic API exposure, the server manages inbox/outbox artifact handling for asynchronous operations and sandbox advertisement for isolated execution environments. These features enable complex workflows where agents can queue tasks, exchange artifacts, and execute code within defined security boundaries.

The apps/server/src/opencode-plugins/openwork-provider-adapters.ts file contains the built-in OpenCode provider that facilitates integration between the server's workspace management and the OpenCode execution engine.

Summary

• The openwork-server transforms local directories into secure HTTP APIs, enabling remote workspace management through the OpenWork ecosystem.
• It implements a dual-role architecture as both a filesystem API provider and an OpenCode proxy gateway, with routing logic centralized in apps/server/src/server.ts.
• Token-based authentication with owner, collaborator, and viewer scopes ensures granular access control, enforced by the approval mechanisms in apps/server/src/approvals.ts.
• The server supports flexible deployment models ranging from global NPM installation to source-based development workflows using pnpm.
• All OpenCode interactions are transparently proxied through /opencode/* endpoints while maintaining consistent security boundaries and permission checks.

Frequently Asked Questions

What authentication methods does openwork-server support?

The openwork-server uses token-based authentication with three distinct privilege levels: owner (full control), collaborator (read/write), and viewer (read-only). Tokens are automatically generated on server startup and validated against the authorization middleware defined in apps/server/src/tokens.ts. All API requests must include a valid bearer token in the Authorization header.

How does openwork-server handle write operations securely?

Write operations require host-level approval managed through apps/server/src/approvals.ts. The server supports multiple approval modes configured via the --approval CLI flag, ranging from auto for development environments to strict manual confirmation for production deployments. Before executing any filesystem modification, the server validates the client's token scope and checks against the configured approval policy.

Can openwork-server run without the OpenWork desktop application?

Yes, the openwork-server operates as a standalone HTTP service independent of the desktop client. It can be installed globally via NPM (npm install -g openwork-server) and started from the command line, making it suitable for headless deployments, CI/CD pipelines, and server environments where only the API access is required.

What is the relationship between openwork-server and OpenCode?

The openwork-server acts as a gateway proxy to the OpenCode engine. All requests to /opencode/* endpoints are forwarded to the embedded OpenCode instance after token validation, as implemented in the main server routing logic. This architecture allows remote clients to execute OpenCode operations while the server enforces workspace-specific security boundaries and access controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}