> ## 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. # 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](https://github.com/stateset/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: ```bash theme={null} 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: ```dotenv theme={null} VITE_API_URL=https://engine.stateset.cloud.stateset.app ``` Then start the desktop development environment: ```bash theme={null} 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: ```text theme={null} 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](/guides/console-web-getting-started), [mobile Console](/guides/console-mobile-getting-started), or the [Desktop architecture reference](/stateset-desktop). 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.