Understanding the OpenWork Den Handoff Flow Between Desktop and Cloud

The OpenWork Den handoff flow employs a copy-paste deep-link protocol to securely transfer one-time authentication tokens between the desktop client and the cloud control plane, eliminating dependency on automatic URL scheme redirects.

The OpenWork Den handoff flow enables seamless authentication when the desktop client requires access to cloud-hosted capabilities. Implemented in the different-ai/openwork repository, this architecture bridges the Electron desktop application and the remote Model Context Protocol (MCP) endpoint through a deliberate browser-to-desktop token exchange. The flow is designed to function across both full Electron environments and headless-web modes where automatic redirects are unavailable.

How the OpenWork Den Handoff Flow Works

The handoff mechanism consists of five discrete stages that move the user from desktop initiation to authenticated cloud session.

Desktop Initiates Cloud Operation

When the desktop application detects that an operation—such as connecting to Google Workspace, Microsoft 365, or installing a marketplace plugin—requires cloud-side OAuth, it triggers the handoff sequence. The client constructs a deep-link URL pointing to https://api.openworklabs.com/mcp/agent with a query parameter indicating desktop authentication mode (?desktopAuth=1). This URL encodes a one-time handoff token that is cryptographically tied to the specific desktop instance.

Browser Handoff with Deep-Links

The desktop application invokes shell.openExternal(handoffUrl) (or an equivalent system browser launcher) to navigate the user away from the native app. In headless-web deployments, the browser is started via a Vite dev server, but the underlying mechanism remains identical. The user lands on the OpenWork Den web interface, where the URL parameters carry the session context required to link the browser action back to the originating desktop client.

User Authentication and Token Generation

Inside the Den cloud interface, the user completes organization sign-in and grants the requested OAuth permissions. Upon successful authentication, the Den generates a short-lived one-time code (or a copyable link) that represents the authenticated session. This code is displayed in the browser with instructions for manual transfer, ensuring compatibility with locked-down corporate environments where automatic protocol handlers are disabled.

Copy-Paste Token Return

The desktop UI presents a Paste sign-in code input field, prompting the user to transfer the code from the browser. If the browser cannot complete automatic handoff due to security policies, the raw link remains accessible for manual copying via any secure channel. This copy-paste fallback guarantees the flow never dead-ends, regardless of browser restrictions or network configurations.

Session Establishment

The desktop client validates the pasted handoff token against the Den's validation endpoint (typically via a POST request to the MCP agent URL with the exchange code). Upon verification, the Den returns a signed session token that the desktop stores for subsequent API calls. The original operation—whether provisioning a model, creating a connection, or downloading a plugin—then proceeds using this authenticated session.

Architecture Components

The OpenWork Den handoff flow relies on three core components working in concert:

• Desktop client: Detects cloud capability requirements, launches system browsers with handoff URLs, and consumes returned tokens to establish local state. According to dev/evals/voiceovers/first-connection.md, this component manages the "desktop → browser → desktop" transition sequence.
• OpenWork Den (cloud): Hosts the organization UI, OAuth flows, and model-provider configurations at api.openworklabs.com. As documented in README.md, this serves as the single source of truth for all organization-level policies.
• Deep-link protocol: A query-string-based mechanism that carries one-time tokens (desktopAuth parameters and exchange codes) between processes. The packages/handsfree/README.md demonstrates how this protocol enables automated agents to invoke the same handoff mechanics.

Implementation Details and Code Examples

MCP Configuration

To register the remote MCP endpoint that drives the handoff, the desktop client uses an opencode.json configuration:

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

This configuration points the desktop to the cloud control plane where handoff tokens are generated and exchanged.

Desktop Integration Code

The following TypeScript pseudo-code illustrates the handoff implementation inside the desktop client:

async function startCloudHandshake() {
  // 1️⃣ Build the deep-link URL with a one-time token
  const handoffUrl = `${process.env.OPENWORK_MCP_URL}?desktopAuth=1`;

  // 2️⃣ Open the system browser (Electron shell)
  shell.openExternal(handoffUrl);

  // 3️⃣ Wait for the user to paste the returned code
  const code = await waitForUserPaste(); // UI shows a textbox

  // 4️⃣ Exchange the code for a signed session
  const session = await fetch(`${process.env.OPENWORK_MCP_URL}/exchange`, {
    method: 'POST',
    body: JSON.stringify({ code })
  }).then(r => r.json());

  // 5️⃣ Store the session token for subsequent API calls
  storeSessionToken(session.accessToken);
}

In headless-web mode (documented in README.md under the Headless web (no Electron) section), the same startCloudHandshake logic applies, though the browser launching mechanism differs.

Security and Design Principles

The handoff flow incorporates several defensive design patterns to ensure secure cross-environment authentication:

• Stateless handoff tokens: Each token is short-lived and cryptographically bound to the requesting desktop instance, preventing replay attacks and session hijacking.
• Browser-agnostic compatibility: The copy-paste requirement ensures functionality across Electron, Chrome, Safari, and restricted corporate browsers that block openExternal callbacks.
• Single source of truth: All organization policies, model configurations, and provider credentials reside exclusively in the Den; the desktop receives only a signed session token, minimizing the attack surface of locally stored secrets.

Summary

• The OpenWork Den handoff flow uses a copy-paste deep-link protocol to bridge desktop and cloud environments without requiring automatic URL scheme redirects.
• The flow progresses through five stages: desktop initiation, browser launch, web authentication, manual token transfer, and session validation.
• Key implementation files include README.md (describing the Den and headless-web modes), packages/handsfree/README.md (automated agent handoffs), and dev/evals/voiceovers/org-download-handoff.md (new member onboarding flows).
• The architecture supports both Electron desktop and headless-web deployments through identical token-exchange mechanics.
• Security relies on short-lived one-time tokens and a manual copy-paste fallback to ensure compatibility with restricted browsing environments.

Frequently Asked Questions

How does the OpenWork Den handoff flow handle corporate browsers that block automatic redirects?

The flow is designed with a copy-paste fallback mechanism. If shell.openExternal() fails or the browser blocks the return path, the user can manually copy the authentication code from the Den web interface and paste it into the desktop application's input field. This ensures the authentication sequence completes successfully even in locked-down environments.

What is the role of the opencode.json configuration in the handoff flow?

The opencode.json file registers the remote MCP endpoint (https://api.openworklabs.com/mcp/agent) that coordinates the handoff. It specifies the cloud URL where the desktop client sends exchange requests and receives signed session tokens, effectively wiring the local application to the Den control plane.

Where is the handoff flow logic documented in the source repository?

Primary documentation resides in README.md under the OpenWork Den and Headless web sections. Concrete implementation examples appear in packages/handsfree/README.md for CLI agents, while end-to-end walkthroughs are detailed in dev/evals/voiceovers/first-connection.md and dev/evals/voiceovers/org-download-handoff.md.

Does the handoff flow work differently in headless-web mode versus the Electron desktop app?

No, the token exchange mechanism remains identical. In headless-web mode, the desktop UI renders in a browser rather than an Electron shell, but the same copy-paste protocol is used because the browser cannot automatically redirect back to a local process. Both modes construct the ?desktopAuth=1 URL and require manual pasting of the return code.

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