​

StateSet Desktop

​

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                  │
└─────────────────────────────────────────┘

• 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

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.

​

Development

​

Prerequisites

​

Setup

git clone https://github.com/stateset/stateset-desktop.git
cd stateset-desktop
npm install
cp .env.example .env

VITE_API_URL=https://engine.stateset.com

​

Running

npm start

./scripts/install-cli.sh
stateset-desktop     # then run from anywhere

​

Related

• Console Overview — the web console
• Console Mobile — the React Native app