# OpenWork Cloud-to-Desktop Handoff Architecture: Secure Session Transfer from Den API to Desktop

> Explore OpenWork's cloud-to-desktop handoff architecture. Learn how secure session transfer from Den API to desktop clients works using deep links and credential exchange.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: architecture
- Published: 2026-08-06

---

**OpenWork uses a short-lived handoff grant exchanged via deep-link to move authenticated sessions from the cloud Den API to local desktop clients, storing the credential in [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) before exchanging it for a permanent session token.**

The `different-ai/openwork` repository implements a secure cloud-to-desktop handoff mechanism that allows users to authenticate once in the web interface and seamlessly transfer that session to a local Electron desktop application. This architecture bridges the cloud control plane (Den API) with the desktop runtime through a cryptographically secure, one-time grant system.

## Architectural Layers of the Handoff System

The handoff flow operates across three distinct logical layers, each responsible for a specific phase of the credential transfer.

### Layer 1: Cloud API Grant Creation

The **Den API** generates a short-lived grant and returns a deep-link URL that the desktop client can consume. In [`evals/packages/behaviors/src/den.ts`](https://github.com/different-ai/openwork/blob/main/evals/packages/behaviors/src/den.ts), the `createDesktopHandoffGrant` function initiates this by calling the `/v1/auth/desktop-handoff` endpoint. This creates a one-time credential that represents the user's authenticated session without exposing the actual session token.

### Layer 2: Desktop Bootstrap Persistence

The **desktop bootstrap** layer persists the grant in [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) and manages the handoff state across application restarts. According to [`packages/types/src/desktop-ipc.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/desktop-ipc.ts), the `DesktopBootstrapConfig` interface defines the `handoff` object that stores the grant string alongside the Den base URL. The bootstrap handling logic in `packages/openwork-bootstrap/bin/openwork.mjs` reads this configuration on startup to detect pending handoffs.

### Layer 3: Runtime Grant Exchange

The **runtime exchange** layer converts the temporary grant into a permanent authentication token. When the desktop application launches and detects a pending handoff, it calls `/v1/auth/exchange-grant` to swap the grant for a real session token. The `exchangeGrant` logic in `packages/openwork-bootstrap/bin/openwork.mjs` handles this transaction, after which the desktop activates the organization and skill context specified in the original handoff.

## Step-by-Step Handoff Flow

The complete cloud-to-desktop handoff follows a six-step sequence that ensures secure, stateless credential transfer:

1. **Desktop requests a handoff URL** from the cloud when the user initiates the connection (e.g., clicking "Connect to Den"). The cloud endpoint returns a JSON payload containing the grant string and a deep-link URL.

2. **Den returns a deep-link** formatted as `openwork://desktop-auth?grant=…&denBaseUrl=…`. This URL encapsulates all parameters needed for the desktop to complete authentication.

3. **Desktop receives the deep-link** via the operating system's URL protocol handler. The Electron main process parses the incoming link and writes the `handoff` object into the bootstrap configuration file.

4. **Bootstrap file persistence** stores the grant in [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json). On the next application launch, the desktop reads this file via the `getDesktopBootstrapConfig` IPC command to retrieve the pending handoff.

5. **Grant exchange for session token** occurs when the desktop POSTs the grant to `/v1/auth/exchange-grant`. The Den API validates the grant against the originating session and returns a permanent authentication token.

6. **Workflow activation** completes the handoff. The desktop stores the token in its auth store and activates the specific organization and skill context, enabling the user to run workflows exactly as if they had signed in directly within the desktop application.

## Implementation Examples

### Creating a Handoff Grant (Cloud Side)

The cloud implementation uses the Den API to generate the handoff grant. This example from [`evals/packages/behaviors/src/den.ts`](https://github.com/different-ai/openwork/blob/main/evals/packages/behaviors/src/den.ts) (line ≈ 361) demonstrates the creation flow:

```typescript
import { denApiFetch } from "@openwork/behaviors";

export async function createDesktopHandoffGrant(member) {
  const result = await denApiFetch(member, "/v1/auth/desktop-handoff", {
    method: "POST",
    headers: { Authorization: `Bearer ${member.sessionToken}` },
  });

  if (!result.response.ok || typeof result.body?.grant !== "string") {
    throw new Error(
      `Desktop handoff create failed: ${result.response.status} ${JSON.stringify(result.body)}`
    );
  }

  // `grant` is a short-lived token; `openworkUrl` contains the deep link.
  return result.body.grant;
}

```

### Consuming the Handoff (Desktop Side)

The desktop bootstrap logic in `packages/openwork-bootstrap/bin/openwork.mjs` (lines ≈ 514-520) handles grant exchange and token storage:

```typescript
import { desktopBridge } from "desktop-ipc";

async function handleDesktopHandoff() {
  const cfg = await desktopBridge.getDesktopBootstrapConfig();

  if (!cfg.handoff?.grant) {
    console.log("No handoff pending");
    return;
  }

  const { grant, denBaseUrl } = cfg.handoff;
  const exchange = await fetch(`${denBaseUrl}/v1/auth/exchange-grant`, {
    method: "POST",
    body: JSON.stringify({ grant }),
    headers: { "Content-Type": "application/json" },
  });

  const { token } = await exchange.json();
  await desktopBridge.setDesktopBootstrapConfig({ /* store token, activate org */ });
}

```

### Triggering the Flow from the UI

The web interface initiates the handoff by requesting a URL from the backend and redirecting to the deep-link:

```tsx
import { useDesktopBridge } from "@/hooks";

export function ConnectButton() {
  const desktop = useDesktopBridge();

  const startHandoff = async () => {
    const handoffUrl = await fetch("/api/create-handoff").then(r => r.text());
    window.location.href = handoffUrl;
  };

  return <button onClick={startHandoff}>Connect to Den</button>;
}

```

## Security and Error Handling

The handoff architecture implements **secure by design** principles. The grant is a one-time, short-lived string that can be exchanged only once, preventing replay attacks. The exchange endpoint validates the grant against the originating Den session, and if the grant is missing or already consumed, the exchange fails with a `desktop_handoff_failed` error. This ensures that even if the deep-link is intercepted, the credential cannot be reused after the legitimate desktop client claims it.

## Key Source Files

Understanding the handoff mechanism requires familiarity with these specific files in the `different-ai/openwork` repository:

- [`packages/types/src/desktop-ipc.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/desktop-ipc.ts) — Defines `DesktopBootstrapConfig` and the `handoff` shape that travels from cloud to desktop.
- `packages/openwork-bootstrap/bin/openwork.mjs` — Implements the bootstrap lifecycle, reads the handoff, and performs the grant exchange.
- [`evals/packages/behaviors/src/den.ts`](https://github.com/different-ai/openwork/blob/main/evals/packages/behaviors/src/den.ts) — Contains the Den API logic for creating handoff grants via `/v1/auth/desktop-handoff`.
- [`evals/runner/journeys/desktop.ts`](https://github.com/different-ai/openwork/blob/main/evals/runner/journeys/desktop.ts) — End-to-end test suite that exercises the complete handoff round-trip.
- `packages/docs/start-here/installer-delivery.mdx` — Documents the `openwork://` URL scheme used by installers to trigger the handoff.

## Summary

- **Three-layer architecture**: Cloud API creates grants, Desktop Bootstrap persists them, and Runtime Exchange converts them to session tokens.
- **Secure one-time grants**: Short-lived, single-use grants prevent replay attacks and ensure credentials cannot be intercepted and reused.
- **Deep-link protocol**: Uses `openwork://desktop-auth` URLs to transfer parameters from browser to desktop application via the OS protocol handler.
- **Bootstrap file storage**: The [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json) file acts as the intermediary state store between deep-link receipt and grant exchange.
- **Token exchange endpoint**: The `/v1/auth/exchange-grant` API validates and converts temporary grants into permanent authentication tokens.

## Frequently Asked Questions

### What is a handoff grant in OpenWork?

A handoff grant is a cryptographically secure, short-lived token generated by the Den API that represents a user's authenticated session without exposing the actual session credentials. It acts as a temporary voucher that the desktop client can exchange for a permanent authentication token, enabling secure session transfer from cloud to desktop.

### How does the desktop application receive the authentication grant?

The desktop receives the grant through a deep-link URL with the `openwork://` scheme. When the user clicks "Connect to Den" in the web interface, the browser redirects to this custom protocol URL, which launches the Electron desktop application and passes the grant and Den base URL as query parameters. The desktop then persists these values in [`desktop-bootstrap.json`](https://github.com/different-ai/openwork/blob/main/desktop-bootstrap.json).

### What happens if the handoff grant expires before use?

If the grant expires or has already been exchanged, the desktop's call to `/v1/auth/exchange-grant` returns a `desktop_handoff_failed` error. The application must then prompt the user to re-initiate the handoff flow from the web interface to generate a fresh grant, as each grant is strictly single-use and time-bound.

### Is the cloud-to-desktop handoff mechanism secure for production use?

Yes, the mechanism is secure by design according to the OpenWork source code. The grant is one-time use only, validated against the originating Den session during exchange, and never transmitted in a reversible format. Even if the deep-link is intercepted, an attacker cannot reuse the grant after the legitimate desktop client has consumed it.