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

# Desktop

> Manage your AI squad from the Desktop desktop app.

Desktop is your command center for Dash. Deploy new squad members, monitor running ones, chat with them directly, and connect them to messaging platforms — all from one place.

It's a **desktop app** that spawns and supervises the HQ for you. For automation, the HQ also exposes a [Management API](/api-reference) you can drive directly.

## Desktop app

The desktop app gives you a visual overview of your entire squad. It features a collapsible sidebar (toggle with ⌘B) for quick navigation.

### Squad

The squad page shows all your deployed squad members with their current status. At a glance, you can see which ones are running, stopped, or in an error state. Click any squad member to manage it.

From the squad list, you can:

* **Start** a stopped squad member
* **Stop** a running squad member
* **Restart** a squad member to pick up config changes
* **Remove** a squad member and clean up its resources

### Squad member detail

Click a squad member to see everything about it. The detail view has three tabs:

<Tabs>
  <Tab title="Configuration">
    See and edit the agent's setup:

    * **Model** — which AI model the agent uses, plus any fallback models
    * **System prompt** — the instructions that shape the agent's behavior
    * **Tools** — which capabilities are enabled (bash, file tools, web search, etc.)
    * **Working directory** — the directory where the agent operates (editable)
    * **Max tokens** — the maximum response length
  </Tab>

  <Tab title="Skills">
    Manage the agent's skills — reusable workflows it can discover and use. Add skill paths or URLs, and see which skills the agent has loaded.
  </Tab>

  <Tab title="Monitor">
    Live operational data for the running agent:

    * **Uptime** — how long the agent has been running
    * **Logs** — streaming stdout/stderr from the agent process
  </Tab>
</Tabs>

### Chat

Talk to any running agent directly from Desktop. The built-in chat interface uses a **tabbed layout** — open multiple conversations at once and switch between them like browser tabs (⌘T to open, ⌘W to close, ⌘1–9 to switch). Responses stream in real time — you see the agent thinking, using tools, and building its answer as it goes.

The empty chat panel shows your recent conversations and deployed agents for quick access. Select which agent to chat with, start a conversation, and messages are routed through the HQ automatically. Conversations persist as sessions, so you can pick up where you left off.

Tool calls render as collapsed cards you can expand for full inputs and results; task lists and failures open on their own. See [Reading tool activity](/chat-with-your-agent#reading-tool-activity) for how the cards work across every client.

### Projects

A shared task board for you and your squad. Organize work into projects and tasks, track status on a Kanban board, and keep an Inbox of everything that needs your attention. Squad members participate too — they can create tasks, update them as they work, and flag a task when they need your input.

See [Projects](/projects) for the full guide.

### AI Providers

Set up API credentials for your AI providers under **Settings → AI Providers**:

<CardGroup cols={3}>
  <Card title="Anthropic" icon="key">
    For Claude models
  </Card>

  <Card title="OpenAI" icon="key">
    For GPT and o-series models
  </Card>

  <Card title="Google" icon="key">
    For Gemini models
  </Card>

  <Card title="Moonshot (Kimi)" icon="key">
    For Kimi K2 models
  </Card>

  <Card title="OpenRouter" icon="key">
    One key for DeepSeek, Llama, Qwen, Grok, and more
  </Card>
</CardGroup>

Enter your API key once and all agents that use that provider share it. Keys are stored in the encrypted secret store.

### Messaging Apps

Connect your agents to external chat platforms like Telegram and WhatsApp under **Settings → Messaging Apps**. From there you can:

* Add a new messaging app connection
* Enter bot credentials
* Configure routing rules that determine which agent receives messages
* Enable or disable connections
* Manage allow lists and deny lists for access control

See [Messaging Apps](/messaging-apps) for setup guides.

### Connectors

Under **Settings → Connectors (MCP)**, install Model Context Protocol (MCP) servers to give your agents access to external tools and services. Add connectors from the MCP ecosystem — Linear, GitHub, a local filesystem, or any other MCP server — and its tools become available to your agents.

### Deploy

A step-by-step wizard to deploy a new agent. Walk through:

<Steps>
  <Step title="Name your agent">
    Give it a name that describes what it does.
  </Step>

  <Step title="Choose a model">
    Pick a primary model and optionally add fallback models. The dropdown is populated live from the provider's API.
  </Step>

  <Step title="Write a system prompt">
    Tell the agent who it is and how to behave.
  </Step>

  <Step title="Select tools">
    Choose which capabilities the agent needs.
  </Step>

  <Step title="Deploy">
    The HQ creates the agent in-process with its own workspace at `~/.dash/workspaces/<agent-id>/`.
  </Step>
</Steps>

## Running Desktop

<Tabs>
  <Tab title="Dev mode">
    ```bash theme={null}
    npm run mc:dev
    ```

    Launches the Electron app in development mode with hot reload.
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    npm run mc:build
    ```

    Builds a production version of the desktop app.
  </Tab>
</Tabs>

For automation or a headless server, run the HQ on its own and drive it through the [Management API](/api-reference) — see [Configuration](/configuration#running-the-hq-standalone).

## How it connects

Desktop communicates with the HQ through two channels:

| Connection     | Protocol  | Default port | Purpose                                                       |
| -------------- | --------- | ------------ | ------------------------------------------------------------- |
| Management API | HTTP      | 9300         | Health checks, deploy/start/stop/restart, credentials, models |
| Channel server | WebSocket | 9200         | Chat messages to and from agents                              |

The desktop app connects to these automatically. On first launch, Desktop spawns the HQ as a background process and stores the auth tokens in the OS keychain. Subsequent launches reconnect to the existing HQ without re-spawning.

<Warning>
  Desktop stores deployment records locally on your machine. HQ tokens are stored in the OS keychain. Back up your keychain if you want to preserve your configuration across machines.
</Warning>

## What's next

<CardGroup cols={2}>
  <Card title="Squad" icon="robot" href="/agents">
    Learn how agents are configured and how they work.
  </Card>

  <Card title="Management API" icon="terminal" href="/api-reference">
    Drive the HQ programmatically — agents, channels, credentials.
  </Card>

  <Card title="Messaging Apps" icon="comments" href="/messaging-apps">
    Connect agents to Telegram, WhatsApp, and more.
  </Card>

  <Card title="Secrets" icon="lock" href="/secrets">
    How encrypted secret storage works.
  </Card>
</CardGroup>