How to Troubleshoot Common Issues in different-ai/openwork: A Complete Guide

Use the built-in openwork-doctor.ps1 script for network/TLS diagnostics, verify opencode.json and desktop-bootstrap.json for stale MCP URLs, and check dev-profile locks when the Electron UI fails to start.

OpenWork is a modular, cross-platform AI-workflow platform that combines an Electron desktop client, a Den control plane, and the OpenCode runtime. When components fail to connect or behave unexpectedly, systematic troubleshooting across these three layers resolves most issues quickly. This guide walks through the diagnostic tools and configuration files that the different-ai/openwork repository provides to identify and fix common problems.

Network and TLS Connection Issues

Most connectivity problems stem from DNS resolution failures, firewall blocks, TLS certificate problems, or corporate proxy interference. The repository includes purpose-built diagnostics for each scenario.

Run the OpenWork-Doctor PowerShell Script

The primary tool for network troubleshooting is scripts/support/openwork-doctor.ps1. This script performs five sequential checks and prints a verdict hint identifying the most likely root cause:

Check	Validation	Typical Verdict
DNS	Resolves hostname via Resolve-DnsName	LIKELY DNS ISSUE
TCP 443	Socket connection with 5s timeout	LIKELY NETWORK/FIREWALL ISSUE
TLS handshake	SslStream callback for certificate/chain status	LIKELY TLS INTERCEPTION or LIKELY MISSING INTERMEDIATE
OpenSSL chain probe	openssl s_client server chain inspection	MISSING INTERMEDIATE CONFIRMED BY OPENSSL
Proxy detection	netsh winhttp show proxy and .DefaultWebProxy	PROXY DETECTED

Execute the script directly from GitHub:

powershell -NoProfile -ExecutionPolicy Bypass -Command `
"`$p=Join-Path `$env:TEMP 'openwork-doctor.ps1'; `
Invoke-WebRequest -UseBasicParsing `
'https://raw.githubusercontent.com/different-ai/openwork/dev/scripts/support/openwork-doctor.ps1' `
-OutFile `$p; & `$p -WebUrl 'https://openwork.example.com' `
-ApiUrl 'https://api.openwork.example.com' -ExpectedIssuerMatch 'DigiCert'`"

The script source is fully inspectable at scripts/support/openwork-doctor.ps1. Detailed documentation mirroring these checks lives in packages/docs/start-here/network-diagnostics.mdx.

MCP and OpenCode Configuration Problems

When the desktop client shows as "connected" but agents cannot call search_capabilities or execute_capability, the MCP entry in OpenCode's configuration typically points to a stale or local server.

Locating Stale MCP URLs

OpenWork's MCP configuration resides in opencode.json. The troubleshooting flow in packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx provides diagnostic prompts that:

1. Print the openwork-cloud MCP entry from all config locations (~/.config/opencode/opencode.json, desktop-bootstrap.json, etc.) without exposing secrets
2. Probe discovered and expected URLs with unauthenticated curl calls to compare OpenAPI catalogs
3. Execute live search_capabilities / execute_capability calls to verify server agreement

Paste this prompt into any OpenWork-connected LLM to automate the diagnosis:

Debug and fix my OpenWork Cloud MCP connection. It may be pointed at a stale or local server
instead of my real OpenWork Cloud server. Work through ALL phases, show your findings after each,
and ask before anything destructive. Never print bearer tokens or Authorization headers — redact them.

My expected cloud web URL: https://app.openworklabs.com

Fixing Stale Local URLs

If the diagnostic reveals localhost addresses or old development servers:

1. Delete desktop-bootstrap.json (or the entire local config directory)
2. Restart the desktop app to mint a fresh MCP token
3. Navigate to Settings → Extensions → Refresh

For manual configuration, create or edit opencode.json:

{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

Place this file in your project root or ~/.config/opencode/, then reload the OpenCode configuration.

Desktop Client Startup Failures

When the Electron UI fails to open despite a visible dev banner, a profile lock conflict is the usual cause.

Reading the Startup Banner

The desktop prints diagnostic information on startup:

[openwork] dev profile=feature-xyz cdp=http://127.0.0.1:9223

This reveals the Chrome DevTools Protocol (CDP) endpoint and active dev profile. The profile directory is tracked via lock files under dev/.warden/.

Resolving Profile Locks

The dev/scripts/dev-web-local.sh script coordinates Vite dev-server ports and Electron CDP ports. When conflicts occur:

• Kill stray Electron processes (running pnpm dev:worktree automatically creates unique profiles per worktree)
• Delete the lock file under dev/.warden/

If the banner displays a CDP URL but no window appears, this confirms a profile lock rather than a fundamental startup failure.

Self-Hosted Den Deployment Issues

For Den instances behind corporate firewalls, enable Outbound Diagnostic via environment variables:

DEN_DIAGNOSTICS_ORIGIN=https://diagnostics.mycompany.internal
DEN_DIAGNOSTICS_BEARER_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

The Den process then contacts your trusted diagnostics service to verify DNS, proxy, and TLS reachability from inside the cluster. See the Den outbound diagnostic section in packages/docs/start-here/network-diagnostics.mdx for implementation details.

Ensure the token is a synthetic 24-character string and that DEN_DIAGNOSTICS_ORIGIN matches your deployment's DNS name—mismatches here produce 403 errors despite valid credentials.

Quick Reference: Symptom-to-Fix Mapping

Symptom	Likely Cause	Resolution
search_capabilities returns partial tool list (e.g., only gmail-drafts)	Stale local MCP server in config	Delete desktop-bootstrap.json, restart app, refresh extensions
TLS "certificate unknown" errors	Missing intermediates or proxy re-signing	Run openwork-doctor.ps1, add corporate root to trust store, or allowlist host
UI never opens but CDP URL visible	Profile lock or port conflict	Kill Electron processes or delete .warden lock file
Den outbound 403 with valid token	Unwhitelisted origin or malformed token	Verify 24-character token format and DNS-origin match

Summary

• Network/TLS problems: Run scripts/support/openwork-doctor.ps1 and consult packages/docs/start-here/network-diagnostics.mdx
• MCP configuration issues: Check opencode.json and desktop-bootstrap.json for stale URLs; use diagnostic prompts in packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx
• Desktop UI failures: Inspect the startup banner for CDP/profile info; resolve locks via dev/scripts/dev-web-local.sh patterns
• Self-hosted Den: Configure DEN_DIAGNOSTICS_ORIGIN and DEN_DIAGNOSTICS_BEARER_TOKEN for firewall-protected deployments

Frequently Asked Questions

How do I know if my MCP is pointing to the wrong server?

The diagnostic prompt in packages/docs/start-here/troubleshooting/diagnostic-prompts.mdx automatically compares your configured MCP URL against the expected cloud URL. If search_capabilities returns tools you don't recognize (or too few tools), this indicates a stale local server. The prompt will flag any localhost entries or mismatched OpenAPI catalogs.

What causes TLS handshake failures in OpenWork?

Corporate proxies that re-sign certificates, missing intermediate certificates in the server chain, or incorrect system trust stores. Run openwork-doctor.ps1 with your target URLs—the script's SslStream callback identifies whether the leaf issuer is an internal proxy CA (LIKELY TLS INTERCEPTION) or whether intermediates are missing (LIKELY MISSING INTERMEDIATE).

Why does the desktop app show a CDP URL but no window appears?

An existing Electron process holds the profile lock or CDP port. The dev banner confirms the app reached CDP initialization; the missing window indicates a conflict. Use pnpm dev:worktree to generate a fresh isolated profile, or manually delete the lock file in dev/.warden/.

How do I diagnose Den connectivity from inside a corporate network?

Set DEN_DIAGNOSTICS_ORIGIN and DEN_DIAGNOSTICS_BEARER_TOKEN environment variables, then restart Den. The process will report its outbound connectivity test results to your specified diagnostics endpoint, revealing DNS, proxy, and TLS problems from the cluster's perspective.

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