Codakey
Play
← Back to openwork

How to Deploy & Use openwork

OpenWork Deployment and Usage Guide

1. Prerequisites

Core Requirements

  • Node.js (latest LTS recommended)
  • pnpm package manager
  • Rust toolchain (for Tauri desktop app)
  • OpenCode CLI (available on PATH)

Platform-Specific Requirements

  • Linux/Wayland users: May need environment flags for WebKitGTK compatibility
  • Arch Linux users: yay -s opencode for OpenCode installation
  • All platforms: Git for cloning the repository

Optional Components

  • Docker: Required for sandbox functionality
  • OpenPackage (opkg): For skill installation (falls back to pnpm dlx opkg if not globally installed)
  • OpenCode Router: For WhatsApp/Slack/Telegram integration

2. Installation

Method 1: Desktop App (Recommended)

  1. Download the latest release from: https://github.com/different-ai/openwork/releases
  2. Install the .dmg (macOS), .exe (Windows), or AppImage/Linux package

Method 2: Build from Source

# Clone the repository
git clone https://github.com/different-ai/openwork.git
cd openwork

# Install Rust toolchain (for Tauri)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Tauri CLI
cargo install tauri-cli

# Install OpenCode CLI (if not already installed)
# Follow instructions at: https://github.com/different-ai/opencode

# Install dependencies
pnpm install

Method 3: Alternate UIs

  • OpenCode Router (WhatsApp bot):

    curl -fsSL https://raw.githubusercontent.com/different-ai/opencode-router/dev/install.sh | bash
opencode-router setup
opencode-router whatsapp login
opencode-router start

  • OpenWork Orchestrator (CLI host):

    npm install -g openwork-orchestrator
openwork start --workspace /path/to/workspace --approval auto

3. Configuration

Workspace Configuration

OpenWork supports two modes:

  1. Host Mode: Runs OpenCode locally on your machine
  2. Client Mode: Connects to an existing OpenCode server by URL

Configuration Files

  • Project scope: <workspace>/opencode.json
  • Global scope: ~/.config/opencode/opencode.json (or $XDG_CONFIG_HOME/opencode/opencode.json)

Example opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-wakatime"]
}

Environment Variables

For Linux/Wayland users experiencing WebKitGTK issues:

# Option 1: Disable dmabuf renderer
WEBKIT_DISABLE_DMABUF_RENDERER=1 openwork

# Option 2: Disable compositing mode
WEBKIT_DISABLE_COMPOSITING_MODE=1 openwork

API Keys and Authentication

  • OpenWork uses OpenCode authentication system
  • Remote server connections require appropriate URL and token configuration
  • WhatsApp integration requires separate setup via OpenCode Router

4. Build & Run

Development Mode

# Run desktop app with hot reload
pnpm dev

# Run web UI only (without desktop shell)
pnpm dev:ui

Production Build

# Type checking
pnpm typecheck

# Build UI only
pnpm build:ui

# Full production build
pnpm build

# Run end-to-end tests
pnpm test:e2e

Architecture Notes

  • Host mode: OpenWork runs a local host stack and connects the UI to it
  • Default runtime: openwork (from openwork-orchestrator)
  • Fallback runtime: direct (spawns opencode serve directly)
  • The UI uses @opencode-ai/sdk/v2/client for server communication

5. Deployment

Desktop Deployment

  1. Build the application: pnpm build
  2. Find packaged application in packages/desktop/src-tauri/target/release/
  3. Distribute platform-specific binaries:
    • macOS: .dmg or .app
    • Windows: .exe installer
    • Linux: AppImage or distribution packages

Server Deployment (OpenWork Orchestrator)

# Install globally
npm install -g openwork-orchestrator

# Start server with auto-approval
openwork start --workspace /path/to/workspace --approval auto

# Or with manual approval
openwork start --workspace /path/to/workspace --approval manual

Cloud Deployment Options

Based on the TypeScript/Tauri stack:

  • Vercel/Netlify: For web UI components
  • Docker containers: For server components
  • Traditional VPS: For full stack deployment
  • AWS/Azure/GCP: Containerized deployment with proper networking

Docker Deployment (if containerized)

FROM node:18-alpine
RUN npm install -g openwork-orchestrator
CMD ["openwork", "start", "--approval", "auto"]

Scaling Considerations

  • OpenWork is designed as local-first but cloud-ready
  • Multiple workspaces can run simultaneously
  • SSE (Server-Sent Events) used for real-time updates
  • Consider load balancing for multiple client connections

6. Troubleshooting

Common Issues

1. OpenWork Crashes on Launch (Linux/Wayland)

Symptoms: WebKitGTK errors like Failed to create GBM buffer Solution:

WEBKIT_DISABLE_DMABUF_RENDERER=1 openwork
# or
WEBKIT_DISABLE_COMPOSITING_MODE=1 openwork

2. OpenCode CLI Not Found

Symptoms: "opencode command not found" errors Solution:

# Install OpenCode CLI
# Check: https://github.com/different-ai/opencode for installation
# Verify it's in your PATH
which opencode

3. Skill Installation Fails

Symptoms: opkg command not found Solution: OpenWork falls back to:

pnpm dlx opkg install <package>

Or install opkg globally.

4. Connection Issues in Client Mode

Symptoms: Unable to connect to remote OpenCode server Solution:

  • Verify server URL and port
  • Check CORS settings on the OpenCode server
  • Ensure proper authentication tokens are configured

5. Permission Errors

Symptoms: File system access denied Solution:

  • On macOS/Linux: Check file permissions
  • On Windows: Run as administrator if needed
  • Configure authorized roots in OpenCode server settings

6. Performance Issues

Symptoms: Slow UI or delayed responses Solution:

  • Check system resource usage
  • Reduce number of active sessions
  • Clear OpenCode cache if needed
  • Monitor network connectivity in client mode

Debug Mode

For advanced troubleshooting:

  1. Check browser developer tools (F12) for web UI issues
  2. Check system logs for desktop app issues
  3. Use --verbose flag if supported by OpenCode CLI
  4. Monitor network traffic for connection issues

Getting Help

← Project overviewView alternatives to openwork →