---
title: Desktop Integration
url: https://arcana.otnelhq.com/docs/desktop
---

New in v0.4.0 

Desktop governance bridge — TUI permission gates now delegate to live Desktop for approval.

# Desktop Integration

**Arcana Desktop** is a local approval and forensic companion that supervises the runtime lifecycle. It renders governance semantics, presents routed approvals, and provides proof inspection — all without leaving your machine.

## What It Is

Desktop is **not** a separate product or authority surface. It's a companion to the local runtime:

- **Runtime lifecycle** — Start, stop, and monitor the Arcana daemon
- **Approval routing** — Receive and respond to approval requests from the TUI
- **Proof inspection** — View RunProof evidence, export proofs, verify chains
- **Restart recovery** — Pending approvals survive daemon and Desktop restarts
- **Native notifications** — OS-level alerts for approval requests

## Governance Bridge

In v0.4.0, the TUI's permission gates can delegate to Desktop:

### How Routing Works

1. **Agent requests action** — The agent wants to execute a consequential tool
2. **Permission gate opens** — TUI shows the approval gate
3. **Route decision** — Based on policy, the gate routes to: @@B6@@
4. **Desktop receives** — Native notification, approval UI with exact request inspection
5. **Operator decides** — Approve or deny through Desktop
6. **Result flows back** — TUI continues execution

### Failed Prompt Queue

If a prompt fails due to a pending approval, it's queued for durable retry:

- Prompts that hit `DESKTOP_REQUIRED` gates are queued
- Once Desktop approves, the queued prompt retries automatically
- Idempotent retries prevent duplicate execution

## Desktop Chat Sync

Desktop can sync chat messages from the TUI session:

- **Streaming text follow** — Desktop follows the TUI's streaming output in real-time
- **Governance-controlled** — Chat sync is a configurable governance policy
- **Privacy-aware** — Only syncs when explicitly enabled

## Approval Routing Modes

| Mode | Behavior | Use Case |
| --- | --- | --- |
| `LOCAL_TUI` | Handle in TUI | Low-risk actions, solo work |
| `DESKTOP_PREFERRED` | Desktop if available, TUI fallback | Default for most actions |
| `DESKTOP_REQUIRED` | Desktop only, never TUI | High-risk actions, team environments |
| `CENTRAL_REQUIRED` | Enterprise console | Compliance-gated actions |

## Configuration

Desktop integration is configured in `arcana.json`:

```json
{
  "governance": {
    "approval_route": "desktop_preferred",
    "chat_sync": true,
    "desktop_heartbeat_interval_ms": 5000
  }
}
```

### Per-Action Route Override

Override routing for specific action types:

```json
{
  "governance": {
    "routes": {
      "file_edit": "desktop_preferred",
      "bash": "desktop_required",
      "network": "desktop_required"
    }
  }
}
```

## Esc Gesture

Press `Esc` in the TUI to:

- Leave the composer and activate spine keys (`j`/`k`/`v`/`a`/`d`)
- Cancel a rejection confirmation (not the approval itself)
- **Not** interrupt a running agent — use the palette command for that

             Note 

Esc is **inert on ACTION GATES** — an accidental Escape cannot reject or decline a request. Gates resolve explicitly with `←`/`→` + `Enter`.

## Runtime API

Desktop communicates with the Arcana daemon via a local HTTP API:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/approvals` | GET | List pending approvals |
| `/approvals/:id` | GET | Get approval details |
| `/approvals/:id/approve` | POST | Approve a request |
| `/approvals/:id/deny` | POST | Deny a request |
| `/approvals/:id/revoke` | POST | Revoke an approval |
| `/sessions` | GET | List active sessions |
| `/proofs/:id` | GET | Get RunProof evidence |
| `/desktop/heartbeat` | POST | Desktop presence signal |

## Related

- [Trust & Security](/docs/trust-boundaries) — Security model and trust boundaries
- [Autonomy Modes](/docs/autonomy-modes) — Control how much autonomy agents have
- [Admin Console](/docs/admin-console) — Enterprise governance and fleet management