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:
   • LOCAL_TUI — Handle in the TUI (default for low-risk)
   • DESKTOP_PREFERRED — Send to Desktop if available, fall back to TUI
   • DESKTOP_REQUIRED — Must be handled by Desktop (never falls back)
   • CENTRAL_REQUIRED — Requires enterprise console approval
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

Configuration

Desktop integration is configured in arcana.json:

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

Per-Action Route Override

Override routing for specific action types:

{
  "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

Runtime API

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

Related