PatchworkOS DOCS
Portal
Developer & Operator Reference Manual

Patchwork OS Runtime & Ecosystem Guide

Comprehensive developer and operator documentation for Patchwork OS (Oolab-labs/patchwork-os), covering how to set up the runtime across different user personas and how to integrate it with IDEs, AI agents, third-party SaaS connectors, and mobile oversight.

Tier 1
Solo Developer

180+ real IDE tools via MCP bridge without daemon overhead.
Tier 2
Power User / Lead

Full governed runtime, YAML recipes, approval gates & Butler UI.
Tier 3
Headless VPS Ops

24/7 Ubuntu systemd, Docker Compose, or PM2 daemon deployment.
Tier 4
Multi-Member Teams

Per-member auth, cryptographic receipts & strict data boundaries.
Part 1

Setting Up Patchwork OS by User Type

Patchwork OS is designed around progressive adoption—from a single developer wiring an IDE to an autonomous, governed multi-member ops deployment.

1

Solo Developer (MCP IDE Bridge Only)

Compat / Ungated Mode
Use Case: You want to give Claude Code, Cursor, Windsurf, or Gemini CLI access to 180+ real IDE tools (LSP symbol navigation, diagnostics, test runners, and debugger evaluation) without running background recipes or the web dashboard.
bash — Solo IDE Bridge Setup 
# 1. Install the binary globally
npm install -g patchwork-os@beta

# 2. Install the VS Code / Cursor / Windsurf companion extension
claude-ide-bridge install-extension

# 3. Start the bridge in your project workspace (compat/ungated mode)
patchwork --workspace . --no-dashboard

# 4. In a second terminal, connect Claude Code to the bridge
export CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true
claude --ide
Verification: Run /mcp inside Claude Code or check ~/.claude/ide/ for the active lockfile (isBridge: true).
2

Power User / Tech Lead (Full Local Governed Runtime + Butler UI)

Governed Profile
Use Case: You want scheduled and event-driven YAML recipes (morning-brief, incident-to-pr, daily-status), the blast-radius approval gate, earned worker autonomy, and the local Next.js dashboard (including the simplified /butler interface).
bash — Governed Local Runtime 
# 1. Scaffold ~/.patchwork, seed starter recipes, and enable "governed" profile
npx patchwork-os@beta init

# 2. Smoke-test the runtime with zero external credentials required
patchwork recipe run daily-status

# 3. Launch the bridge + recipe daemon + local web dashboard
patchwork start

Interfaces Available

Full Operator Dashboard
http://localhost:3200

Recipes, Approvals, Workers, Decision Receipts, Replay Debugger, and Marketplace.

Butler Mode
http://localhost:3200/butler

Streamlined, high-signal executive home view for non-technical or busy operators to review pending approvals, inbox digests, and worker status at a glance.

Interactive Terminal UI (TUI)
patchwork

Run patchwork with no arguments in any terminal for real-time keyboard-driven oversight.

3

Headless VPS / Always-On Cloud Operator (Ubuntu / Docker / PM2)

24/7 Daemon Mode
Use Case: Running Patchwork OS 24/7 on a remote Ubuntu VPS so webhooks, cron recipes, and mobile push approvals work even when your laptop is closed.

Option A Native Systemd / Bootstrap Script (deploy/)

The repository includes turnkey provisioning scripts in deploy/:

bash — Ubuntu 22.04 / 24.04 VPS Bootstrapper 
# On a fresh Ubuntu 22.04/24.04 VPS:
git clone https://github.com/Oolab-labs/patchwork-os.git
cd patchwork-os

# 1. Run the VPS bootstrapper (installs Node, Nginx, Certbot, and sets up env)
sudo bash deploy/bootstrap-new-vps.sh

# 2. Copy and configure your VPS environment variables
cp .env.vps.example ~/.patchwork/.env
nano ~/.patchwork/.env

# 3. Install the systemd units (claude-ide-bridge@.service + dashboard)
sudo bash deploy/install-vps-service.sh

Note: You can also manage the processes via PM2 using deploy/ecosystem.config.js.example or macOS LaunchAgents via deploy/macos/install-mac-bridge.sh.

Option B Docker Compose

bash — Containerized Deployment 
cp .env.vps.example .env
docker compose up -d --build
4

Multi-Member Engineering & Ops Teams (Per-Member Auth & Boundaries)

ADRs 0017, 0020, 0021, 0024
Use Case: Multiple team members sharing a hosted/VPS Patchwork OS instance with individual accountability on decision receipts, per-member sessions, and data boundaries (ADRs 0020 & 0021).
Step 1 • Roster

Configure Team Roster (~/.patchwork/config.json)

Define member accounts and roles in your runtime configuration so each operator logs in with their own identity rather than a shared admin token.

Step 2 • ADR 0017

Actor Attribution on Receipts

When an operator approves or rejects a gated action in /approvals, the durable decision receipt (~/.patchwork/receipts/) cryptographically records the specific memberId who authorized the blast radius.

Step 3 • ADR 0024

Information & Control Boundaries

Configure worker boundaries (/workers or automation-policy.json) to enforce field-level data labels and strict forbidden tool lists that cannot be overridden even by human approvers.

Part 2

Platform & Ecosystem Integrations

Connect Patchwork OS across AI coding clients, 13+ first-party SaaS platforms, cloud & local Apple Silicon model drivers, inbound webhooks, and mobile VAPID push oversight.

1. AI Coding Agents & IDEs (MCP Integration)

Patchwork OS acts as a universal Model Context Protocol (MCP) server and governance proxy (PreToolUse hook) across major AI clients.

Client / Platform Integration File / Method Setup Command / Configuration
Claude Code CLI
~/.claude/settings.json + .claude-plugin patchwork-os init automatically registers the PreToolUse approval hook (claude-ide-bridge-plugin/scripts/pre-tool-use.sh) so write-tier tools pause for approval.
Cursor
.cursor/mcp.json & .cursorrules Point Cursor's MCP settings to the local bridge SSE/WebSocket endpoint (http://localhost:3200/api/bridge) and install the .vsix companion extension.
Gemini CLI
.gemini/settings.json Pre-configured in .gemini/settings.json at the repo root to connect directly to the Patchwork MCP server.
Windsurf / Antigravity / VS Code
Companion Extension + MCP Run claude-ide-bridge install-extension to load the IDE extension that exposes live LSP, diagnostics, and debug sessions to the bridge.

2. SaaS Platform Connectors (OAuth 2.0 & API Keys)

Ships with 13+ first-party platform connectors (visible in /connections and dashboard/public/connectors/).

0600 Local Key Storage
Engineering & Incident
github gitlab linear jira sentry
Communication
slack discord gmail
Knowledge & Workspace
notion confluence google-drive google-calendar
CRM & Project Ops
hubspot asana
Method A

Via the Web Dashboard (OAuth 2.0 Flow)

  1. Navigate to http://localhost:3200/connections.
  2. Click Add Connection (AddConnectionModal) and select your platform (e.g., GitHub, Slack, Linear, Google Calendar).
  3. The dashboard routes through /api/connections/[connector]/auth → provider OAuth screen → /api/connections/[connector]/callback.
  4. Credentials are stored locally with 0600 permissions inside ~/.patchwork/config.json (never synced to an external cloud).
  5. Click Test Connection (/api/connections/[connector]/test) or check the Connector Health Panel to verify token scopes.
Method B

Via Headless CLI / Config (~/.patchwork/config.json)

For headless servers or PAT/API-key authentication, inspect required scopes or add credentials directly:

bash — Recipe Preflight Check 
# Inspect which connectors and environment variables a recipe requires
patchwork recipe preflight ~/.patchwork/recipes/morning-brief.yaml
json — ~/.patchwork/config.json 
{
  "profile": "governed",
  "connectors": {
    "github": { "token": "ghp_your_personal_access_token" },
    "linear": { "apiKey": "lin_api_your_key" },
    "slack": { "botToken": "xoxb-your-bot-token", "signingSecret": "..." },
    "sentry": { "authToken": "sntrys_...", "org": "your-org" }
  }
}

3. Model Driver Integrations (Cloud LLMs, Subprocess & Local Apple Silicon)

Patchwork OS decouples recipes from the underlying model provider and supports cost-aware routing (ADR 0015).

ADR 0015 Cost-Aware Routing
Zero-API-Key

Subprocess Driver (--driver subprocess)

Piggybacks on your existing authenticated local claude CLI subscription—no separate API key required.

Multi-Cloud

Cloud Model Drivers

Configure ANTHROPIC_API_KEY (Claude Opus/Sonnet/Haiku), OPENAI_API_KEY, GEMINI_API_KEY, or XAI_API_KEY in ~/.patchwork/config.json.

Air-Gapped Local

Ollama & Apple Silicon MLX

  • Ollama: Point worker driver to ollama/<model-name> (http://localhost:11434).
  • Native MLX (docs/mlx-integration.md): Local MLX inference on macOS Apple Silicon for zero-egress recipe steps and counterfactual simulations.

4. Inbound Webhooks & Event Fanout

Trigger recipes automatically from external platforms (GitHub PRs, Sentry alerts, Linear updates, Slack events).

ADR 0009 Fanout Receiver
1
Expose your Patchwork bridge endpoint via Nginx (deploy/nginx-claude-bridge.conf.template) or a secure tunnel (deploy/macos/com.patchwork.tunnel.plist.template).
2
Point the external service's webhook URL to your Patchwork webhook fanout receiver (ADR 0009).
3
Bind the event trigger inside your declarative recipe YAML.
yaml — Recipe Webhook Trigger 
triggers:
  - type: webhook
    source: github
    event: pull_request.opened

5. Mobile Oversight & PWA Push Notifications

Approve or halt high-blast-radius agent actions from your phone using Web Push (VAPID) and the Progressive Web App (docs/mobile-oversight.md).

Remote Kill Switch Ready
Step 01
Open Dashboard URL

Access your Patchwork Dashboard on mobile via Tailscale, Cloudflare Tunnel, or your Nginx HTTPS domain.

Step 02
Install PWA

Tap Install App / Add to Home Screen (powered by manifest.json and sw.js).

Step 03
Enable Push

Go to Settings → Mobile Oversight (MobileSection.tsx) and toggle Enable Push Notifications.

Step 04
VAPID Handshake

Registers device against /api/push/subscribe using local VAPID keys (/api/push/vapid-key).

Step 05
Test & Verify

Click Send Test Notification (/api/push/test). Risky steps link straight to /approvals/[callId] with Emergency Kill Switch (/api/relay/halt).