Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
OpenWork is an open-source alternative to Claude Cowork and Codex, designed as a practical control surface for agentic work. It functions as a graphical user interface (GUI) for OpenCode, allowing users to run local and remote agent workflows, manage skills, and connect to Model Context Protocol (MCP) servers from a single desktop application.
The project is built on a "local-first, cloud-ready" philosophy, enabling users to start workflows on their local machine and transition to cloud-hosted workers when needed. It prioritizes composability and extensibility, allowing developers to build reusable agent setups that can be shipped across organizations with built-in guardrails and policy controls.
Sources: README.md:1-15, AGENTS.md:3-15, ee/apps/landing/public/llms.txt:3-12
Core Architecture and Modes
OpenWork operates primarily through two modes of execution: Host Mode and Client Mode. The application architecture orchestrates a stack involving the UI, the OpenWork server, and the underlying OpenCode engine.
Operational Modes
| Mode | Description |
|---|---|
| Host Mode | Runs the full host stack (OpenCode, OpenWork server) locally on the user's computer using a selected project folder as the workspace. |
| Client Mode | Connects the desktop UI to an existing local or remote OpenCode server via a URL. |
| Server Mode | Operates as an API surface that can be consumed by various clients (Desktop app, Slack, Telegram, etc.). |
Sources: README.md:95-125, AGENTS.md:5-15, ee/apps/landing/public/llms.txt:14-20
Technical Stack and Architecture
The UI communicates with the server using the @opencode-ai/sdk/v2/client. This SDK facilitates session management, prompt submission, and real-time updates via Server-Sent Events (SSE) subscriptions to the /event endpoint.
Sources: README.md:126-140, AGENTS.md:5-10, evals/README.md:7-12
Workspace and Agent Initialization
When a workspace is initialized, the system ensures the presence of specific configuration and agent files. This logic is handled by the ensureWorkspaceFiles function, which manages the lifecycle of project-specific settings.
Initialization Components
- OpenWork Configuration: Managed via
openwork.json, defining versioning, workspace presets (e.g., "starter"), and authorized roots. - OpenCode Configuration: Defined in
opencode.jsonc, setting thedefault_agentand mandatory plugins likeopencode-chrome-devtools. - Default Agent: A default
openwork.mdagent file is created in.opencode/agents/. This file contains the system prompt and instructions for the LLM. - Artifact Guidance: A standardized section injected into the agent prompt to guide the LLM on how to handle deliverables like
.csv,.xlsx, and.mdfiles.
Sources: apps/server/src/workspace-init.ts:13-100, apps/server/src/workspace-init.ts:137-230
Workspace Logic Flow
Skills and Extensions
Skills are specialized modules that extend the agent's capabilities with workflows, tool integrations, or specialized knowledge.
Skill Structure
A skill is represented as a folder located under .opencode/skills/<skill-name>/, anchored by a mandatory SKILL.md file. The recommended structure includes:
- SKILL.md: The core logic and metadata (Frontmatter).
- README.md: Documentation for the skill.
- templates/: Reusable prompt or file templates.
- scripts/: Support scripts for tool execution.
Plugin Management
Plugins are native extensions for OpenCode. OpenWork manages these by reading and writing to opencode.json at either the project scope (<workspace>/opencode.json) or global scope (~/.config/opencode/opencode.json).
Sources: apps/app/src/app/data/skill-creator.md:7-25, README.md:148-165, ee/apps/landing/public/llms.txt:32-38
Security and Data Privacy
OpenWork is designed with a "privacy-first" approach, particularly for enterprise deployments. In a self-hosted environment, OpenWork receives zero customer data.
Data Handling Matrix
| Data Type | Self-Hosted | Cloud |
|---|---|---|
| Source Code | Stays local; never leaves infrastructure. | Accessed at runtime via provider; not stored. |
| API Keys | Stored in local keychain/env vars. | Held by LLM provider; not by OpenWork. |
| Prompts | Stays local. | Sent to LLM provider; not logged. |
| Telemetry | None / Zero phone-home. | Anonymous via PostHog (can be disabled). |
Sources: ee/apps/landing/components/landing-trust.tsx:50-60, ee/apps/landing/components/landing-trust.tsx:110-140, AGENTS.md:5-15
Development and Contribution
The project uses a modern TypeScript-based stack with a focus on simple, concise solutions.
- Package Manager: Mandatory use of
pnpm. - Runtime: Node.js and Bun (1.3.9+).
- UI Framework: React with Tailwind CSS, shadcn/ui (Base UI), and TanStack Query.
- Desktop Shell: Tauri (Rust toolchain required).
- ORM: Drizzle.
Development Workflow
Developers are expected to run end-to-end tests (pnpm test:e2e) and provide video evidence of successful flows in PRs. The environment supports OPENWORK_DEV_MODE=1, which isolates OpenCode state during development to prevent contamination of global user configurations.
Sources: AGENTS.md:32-60, README.md:175-215, README.md:238-250
Summary
OpenWork serves as a comprehensive platform for deploying agentic workflows. By providing a GUI for OpenCode and supporting local-first execution, it bridges the gap between CLI-based developer tools and user-friendly enterprise applications. Its architecture supports extensive customization through skills and MCP servers while maintaining strict data privacy through self-hosting capabilities.