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

# StateSet Desktop

> The Electron desktop app for running and supervising autonomous customer service agents with real-time streaming.

# StateSet Desktop

An Electron desktop application for managing autonomous customer service agents, with a
real-time streaming UI over the StateSet Engine API.

## Features

* **Autonomous AI agents** running in continuous loops that handle customer service tasks.
* **Real-time streaming** — SSE-based live updates showing agent thinking, tool calls, and
  responses.
* **Platform integrations** — OAuth connections for Shopify, Gorgias, Zendesk, and more.
* **Multi-brand support** — manage multiple brands with separate configurations.
* **Loop control** — pause, resume, and stop agents at any time.
* **Metrics dashboard** — token usage, tool calls, and agent performance.

## Architecture

```
┌─────────────────────────────────────────┐
│           Electron Desktop App          │
│                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  │
│  │  Login  │  │Dashboard│  │ Console │  │
│  └─────────┘  └─────────┘  └─────────┘  │
│                    │                    │
│              SSE Stream                 │
└────────────────────┼────────────────────┘
                     ▼
┌─────────────────────────────────────────┐
│          StateSet Engine API            │
│                                         │
│  Agent Sessions → Sandbox Execution     │
│  OAuth → Platform APIs                  │
└─────────────────────────────────────────┘
```

The app runs as three connected layers:

| Layer                     | Responsibility                                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Electron main process** | Creates the window and tray behavior, enforces navigation and security policy, handles secure key storage, and exposes IPC handlers for auth, store, OAuth, notifications, and updates |
| **Preload bridge**        | Exposes a minimal `window.electronAPI` surface so the renderer can call approved capabilities **without direct Node.js access**                                                        |
| **React renderer**        | Boots the UI, initializes auth and preferences, and renders protected routes once authenticated                                                                                        |

At runtime:

* Auth state is restored from secure storage and validated with `GET /api/v1/auth/me`.
* API requests flow through a client providing retry, timeout, circuit breaking, validation,
  and request dedupe.
* React Query holds server state; Zustand holds app and session UI state.
* The agent console streams live events over SSE.
* An IndexedDB offline cache provides fallback reads for key lists.

## Request lifecycle

Starting a stopped agent from the dashboard:

1. The user clicks start.
2. An optimistic mutation marks the session `starting` immediately, so the UI stays responsive.
3. The mutation calls `startSession(tenantId, brandId, sessionId)`.
4. That issues `POST /api/v1/tenants/:tenantId/brands/:brandId/agents/:sessionId/start`.
5. The request layer handles retry, timeout, and circuit-breaker concerns, and records metrics.
6. On success, React Query invalidates session queries and refetches canonical state.
7. The UI re-renders with the authoritative status — `running` or `paused` — from the API.
8. In the Agent Console, the stream hook connects to the SSE endpoint.
9. SSE events (`thinking`, `message`, `tool_call`, `metrics`, `status_changed`) stream in and
   update the live timeline and metrics panel.
10. Background sync updates tray status and optionally raises desktop notifications.

<Note>
  The optimistic `starting` state is a UI affordance only. Canonical status always comes from the
  API refetch in step 6 — don't treat the optimistic value as authoritative.
</Note>

## Development

### Prerequisites

Node.js 22.12+ (see `.nvmrc`).

### Setup

```bash theme={null}
git clone https://github.com/stateset/stateset-desktop.git
cd stateset-desktop
npm install
cp .env.example .env
```

Configure the API URL in `.env`:

```bash theme={null}
VITE_API_URL=https://engine.stateset.com
```

### Running

```bash theme={null}
npm start
```

This starts the Vite dev server on port 5173, launches Electron pointing at it, and enables
hot module replacement.

For a globally available command:

```bash theme={null}
./scripts/install-cli.sh
stateset-desktop     # then run from anywhere
```

## Related

* [Console Overview](/stateset-console/stateset-console-overview) — the web console
* [Console Mobile](/stateset-console/stateset-console-mobile) — the React Native app