> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop Architecture

> A local-first desktop client — execution on your machine, assets in the cloud

The Profy desktop app is more than a web wrapper: it moves the AI's entire **execution plane** onto your computer, while keeping **assets** — your account, skill library, and expert content — centrally managed in the cloud. This split lets the desktop operate on your local files, browser, and screen, while still sharing the same skill and expert ecosystem with the web and mobile clients.

## The Two-Plane Model

One rule explains the whole architecture: **data lives where it is consumed**.

| Plane                    | Location      | Contents                                                                                                      |
| ------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------- |
| Execution plane          | Your computer | Agent loop, tool execution, sandbox isolation, session history, plugin preferences, recordings                |
| Asset & settlement plane | Cloud         | Authentication, skill library, expert content, memory graph, billing & entitlements, marketplace distribution |

<CardGroup cols={2}>
  <Card title="Execution stays local" icon="laptop">
    The agent loop runs directly on your machine, isolated by an OS-level sandbox (macOS Seatbelt). Working with local files, driving the browser, and recording the screen never round-trip through the cloud.
  </Card>

  <Card title="Assets stay in the cloud" icon="cloud">
    Skills, experts, and memory have a single source of truth in the cloud — a skill created on the web is instantly available on desktop, and skills distilled on desktop show up on every other device.
  </Card>
</CardGroup>

## Two-Process Architecture

The desktop app is built from two cooperating processes:

```mermaid theme={null}
graph LR
    subgraph Your computer
        R[Renderer<br/>Web UI] <-->|IPC| E[Electron Main]
        E <-->|stdio JSON-RPC| S[Python Sidecar<br/>Agent loop]
        E --> B[Browser control CDP]
        E --> C[Computer use CUA]
        S --> L[(Local state<br/>~/.profy)]
    end
    S -->|prepare / finalize| Core[Cloud Core API]
    S -->|model inference| LLM[Model gateway]
```

* **Electron main process**: windows, browser automation (CDP), computer use, the recording overlay, and other system capabilities
* **Python sidecar**: runs the full agent loop; only two kinds of cloud communication remain — an entitlement check when a conversation starts (prepare) and a settlement write-back when it ends (finalize)

## Local-First Session State

Desktop session history is stored as append-only JSONL files under `~/.profy/` on your machine — the **single source of truth** for conversations:

<Steps>
  <Step title="Every turn lands on disk immediately">
    Each turn (user message, AI reply, tool calls) is written synchronously to a local rollout file. Cross-turn context is rebuilt from local history — cloud hiccups never break your conversation context.
  </Step>

  <Step title="Cloud projection with async compensation">
    After a conversation ends, a "projection" is sent to the cloud for web-side visibility and billing settlement. Failed write-backs are never dropped: they enter a local retry queue with exponential backoff until eventually consistent.
  </Step>

  <Step title="The UI reads local disk directly">
    Session lists and message history are read straight from local disk on desktop — your full history is browsable offline. Cloud sessions are merged into the view, with the local version winning for the same session.
  </Step>
</Steps>

Plugin activation is persisted locally too: once enabled, a plugin stays active across sessions and restarts — no need to reselect it every time.

## Authentication: Access + Refresh Credentials

Desktop background processes never hold a server-side secret (server secrets never leave the datacenter). Instead they use the same dual-credential model as leading desktop clients:

```mermaid theme={null}
sequenceDiagram
    participant D as Desktop Sidecar
    participant Core as Cloud Core
    D->>Core: Mint request with session token (refresh credential)
    Core-->>D: Issues a JWT (access credential)
    D->>Core: All business calls use Authorization: Bearer
    Note over D: Auto re-mint before expiry, seamless renewal
```

* **Session token = refresh credential**: captured at login, revocable server-side at any time, only ever touches the mint endpoint
* **JWT = access credential**: stateless and verifiable, used on every business-call hot path

## The Record → Skill → Replay Loop

A capability loop unique to the desktop:

<Steps>
  <Step title="Record">
    Start recording and system-level event capture logs your workflow (clicks, typing, navigation). Recording data stays local.
  </Step>

  <Step title="Distill into a skill">
    Stopping the recording automatically triggers AI analysis: it parses the event stream, extracts intent, and saves a structured skill to your cloud skill library — instantly available on all devices.
  </Step>

  <Step title="Replay">
    Activate the skill in a new conversation and the AI reproduces the workflow through browser automation (trusted input events) and computer use, verifying the result after each step.
  </Step>
</Steps>

## The Billing Gate

Local execution does not bypass billing: before every conversation, the sidecar must pass the cloud entitlement check (prepare) — if it fails, the conversation is blocked. This mirrors Codex's design: **threads live locally, inference is guarded by a cloud billing gate**. In desktop mode the cloud never provisions a cloud sandbox (execution is already local), so no redundant resources are spent.

## How It Compares

| Capability      | Profy Desktop                 | Codex (ChatGPT.app)     | Notes                                                                            |
| --------------- | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------- |
| Session history | Local JSONL                   | Local JSONL             | Same: local-first                                                                |
| Skill storage   | Cloud (shared across devices) | Local folders           | Deliberate difference: Profy skills feed the marketplace and sync across devices |
| Authentication  | Session token + JWT           | OAuth access + refresh  | Same shape: user credentials, no server secrets                                  |
| Execution       | Local + OS sandbox            | Local + OS sandbox      | Same                                                                             |
| Billing         | Cloud prepare gate            | Cloud inference gateway | Same: local execution, cloud settlement                                          |