Get Started with StateSet Desktop

Install the desktop app, connect your Engine workspace, select tools, and verify your first bounded agent session.

Outcome: an agent session in the intended tenant and brand performs one bounded task, and you inspect its tool results and authoritative session status.

StateSet Desktop is an Electron app connected to the Engine. Its window is the control surface; agent execution depends on the configured backend and sandbox. Installing the app does not provision every service or make cloud agents run locally.

Before you begin

Have access to your Engine workspace, its tenant and brand, and a supported sign-in method. For a task that reads business data, also have a connection authorized for that system. A ResponseCX or NSR service key is not automatically a Desktop Engine login key.

1. Install or run the app

For a packaged app, use your team’s approved distribution or the assets provided by the StateSet Desktop releases. Choose the available asset for your operating system and CPU architecture. The repository’s packaging configuration includes macOS, Windows, and Linux targets; this does not guarantee that every asset is available for every release.

For development, use Node.js 22.12+ and the repository’s npm toolchain:

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

Set the Engine origin in .env for your deployment. The checked repository uses:

VITE_API_URL=https://engine.stateset.cloud.stateset.app

Then start the desktop development environment:

npm start

This builds the Electron entry point, starts Vite, and launches Electron. A browser-only Vite page does not exercise the native credential store, OAuth bridge, or MCP probe. Do not put private API keys in VITE_* variables; configure credentials through the app.

2. Sign in and verify scope

The login screen offers Email and API Key modes. Use the mode supported by your deployment. The email/password flow can return provisioned Engine credentials and workspace context; the API-key path validates the key against the Engine. If you need an account, use the app’s sign-up path when enabled or obtain access from your administrator.

Check the tenant and selected brand before creating work. If native secure storage is unavailable, the login UI warns that the key is stored for the session only. A failed login should be diagnosed against the configured Engine, not by trying unrelated service credentials.

3. Connect the tools your task needs

Open Connections and configure one required integration or hosted MCP server. For hosted MCP connections, use the app’s verification action to perform an actual initialize and tool-discovery handshake. Inspect the returned server identity and tools.

Connection type	What to verify
Hosted StateSet MCP	Correct server credential and tenant-specific endpoint where required
Custom HTTP MCP	Intended endpoint, accepted credential, and discovered tools
Local-only stdio catalog entry	Use its configuration in a compatible local MCP host; a cloud agent cannot reach a process on your laptop merely because it appears in the catalog

A successful desktop probe proves that the desktop can reach the server. Verify the cloud execution environment can reach it too. Credentials may use the backend vault or encrypted local fallback depending on deployment; a locally saved connection is not proof of cloud availability.

4. Create one bounded session

Use the dashboard’s create-agent flow. Choose the appropriate agent type or template, give the session a recognizable name, and inspect its configuration before selecting Create Agent.

Review Custom Instructions, Max Iterations, Loop Interval (ms), and selected MCP servers. Set a small iteration bound for the first exercise rather than accepting a long-running loop without review. Resolve any warning about selected but unconnected servers.

Use a task like this, replacing the bracketed values:

Read only. Inspect [one test order or ticket] using the connected [system].
Confirm the record identifier and summarize its current state with evidence
from the tool results. If access or a required tool is missing, report the
blocker. Do not change the record, send messages, issue refunds, or create
follow-up work. Stop after this single inspection.

The prompt sets task intent; enforce allowed operations with the actual credentials, tools, and backend policy. Running a session can consume model and execution resources.

5. Inspect execution and stop deliberately

Start the intended session and open its Agent Console. Inspect streamed messages, tool calls, metrics, and status events. Compare the answer with the retrieved record rather than treating a fluent response as proof of a successful integration.

The dashboard can show an optimistic starting state before the backend confirms the result. Refresh and verify canonical session state after start, pause, resume, or stop. Losing the stream, closing the window, or seeing cached data does not prove the remote session stopped.

Complete when: you have the correct tenant/brand, session ID, observed tool result, and a verified final or stopped state. Save those together for the next operator.

Troubleshooting

Symptom	Next check
App opens but login fails	Engine origin, credential type, and workspace provisioning
Brand or session list is empty	Selected tenant/brand, access, and whether the view is cached
MCP probe succeeds but task cannot use tools	Session’s selected server IDs, saved credentials, and backend network access
A local-only server cannot be selected for cloud execution	Use a compatible local host or a supported hosted connection
Timeline stops updating	Stream connection and backend session status before restarting work
Stop was clicked but work still appears active	Read authoritative session status and reconcile in-flight effects

Continue with web Console, mobile Console, or the Desktop architecture reference.

Source basis: stateset-desktop README, package scripts, Login, Dashboard, CreateAgentDialog, Engine API client, and docs/MCP_SERVERS.md, reviewed 2026-09-20. Installation and live Engine execution were not performed as part of writing this guide.