Squad

A squad member is part of your AI team. It has a model to think with, instructions to follow, and tools to get work done. You tell it what to do, and it figures out how.

What is a squad member?

A squad member combines four things:

A model — the AI brain (Claude, GPT, Gemini, etc.)
A system prompt — instructions that shape the agent’s personality and behavior
Tools — capabilities like running commands, reading files, or searching the web
Skills — reusable workflows the agent can discover and use on demand

When you send a message, the squad member reads it, reasons about what to do, uses tools if needed, and responds. It does this autonomously — no hand-holding required.

Squad member configuration

You configure each squad member in Desktop’s Deploy wizard (and edit it later from the squad member’s Configuration tab). Behind the scenes, a squad member’s saved configuration looks like this:

{
  "name": "assistant",
  "model": "anthropic/claude-sonnet-4-20250514",
  "systemPrompt": "You are a helpful assistant that specializes in research.",
  "tools": ["bash", "read", "write", "edit", "grep", "find", "web_search"],
  "maxTokens": 4096,
  "fallbackModels": ["openai/gpt-4o", "google/gemini-2.0-flash"]
}

Field	Type	Required	Description
`model`	`string`	yes	The AI model to use (e.g. `anthropic/claude-sonnet-4-20250514`, `openai/gpt-4o`, `google/gemini-2.0-flash`)
`systemPrompt`	`string`	yes	Instructions that tell the agent who it is and how to behave
`tools`	`string[]`	no	Which tools the agent can use. See Tools for the full list
`maxTokens`	`number`	no	Maximum response length in tokens (default: `4096`)
`workspace`	`string`	no	Directory where the agent operates (default: `~/.dash/workspaces/<agent-id>`)
`fallbackModels`	`string[]`	no	Backup models to try if the primary model fails

Desktop saves your squad members to ~/.dash/gateway/agents.json and the HQ restores them on restart.

Available models

Dash supports models from several providers. Set the model field using the provider/model format:

Anthropic

Claude Opus 4
Claude Sonnet 4
Claude Haiku 4.5

OpenAI

GPT-4o
o3 mini

Google

Gemini 2.0 Flash

Moonshot (Kimi)

Kimi K2.6
Kimi K2.7 Code

OpenRouter

openrouter/deepseek/deepseek-r1
openrouter/qwen/qwen3-max
openrouter/x-ai/grok-4.3

See AI Providers for credentials setup and model routing details.

Available tools

Pick the tools your squad member needs. Each tool gives a specific capability:

Tool	What it does
`bash`	Run terminal commands on the system
`read`	Read files from the project
`write`	Create new files in the project
`edit`	Make changes to existing files
`ls`	See what files and folders exist
`find`	Find files by name or pattern
`grep`	Search for text inside files
`web_search`	Search the internet for information
`web_fetch`	Download content from web pages
`mcp`	Connect to external services and tools
`create_skill`, `install_skill`, `remove_skill`	Let the agent manage its own skills

See Tools for detailed descriptions and sandboxing behavior.

Fallback models

If your primary model is unavailable or hits a rate limit, the squad member automatically tries the next model in the chain.

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "fallbackModels": ["openai/gpt-4o", "google/gemini-2.0-flash"]
}

The squad member tries models in order: primary first, then each fallback. This keeps your squad member running even if one provider has an outage. Each model can be from a different provider — just make sure you have the right API keys set up.

Workspace

Every squad member gets its own workspace directory. This is where tool operations happen. By default it’s ~/.dash/workspaces/<agent-id> — you can open that folder in Finder or your editor to drop in files for the squad member to work with, or set a custom path in the deploy wizard. The workspace directory is created automatically if it does not exist. Tools operate within this directory:

bash uses the workspace as its working directory
read, write, edit resolve file paths relative to the workspace
File tools are sandboxed — they cannot access files outside the workspace boundary

If no workspace is configured, tools operate without path restrictions. Always set a workspace for squad members that use file or shell tools.

Lifecycle

Squad members are deployed as background processes. Each squad member goes through these states:

State	Meaning
`provisioning`	The squad member is starting up
`running`	The squad member is live and accepting messages
`stopped`	The squad member has been stopped (manually or by the system)
`error`	Something went wrong during startup or runtime

You can start, stop, restart, and remove squad members at any time from Desktop’s Squad page — click a squad member to manage it. For automation, the same operations are available on the Management API.

Sessions

Every conversation with a squad member is saved as a session. Sessions are stored as append-only JSONL files (one event per line) so they are easy to inspect and crash-safe.

~/.dash/gateway/sessions/{agent-name}/{conversationId}/

When you send a new message, the squad member loads the session history first. This means it remembers everything from the conversation — previous messages, tool results, and its own responses. Context carries across messages automatically.

Multiple squad members

You can run as many squad members as you need. Each one is independent — different model, different instructions, different tools. Deploy each from Desktop; their configurations look like this:

[
  {
    "name": "researcher",
    "model": "anthropic/claude-sonnet-4-20250514",
    "systemPrompt": "You are a research assistant. Find information and summarize it clearly.",
    "tools": ["web_search", "web_fetch", "read", "write"]
  },
  {
    "name": "coder",
    "model": "anthropic/claude-opus-4-20250514",
    "systemPrompt": "You are a senior software engineer. Write clean, tested code.",
    "tools": ["bash", "read", "write", "edit", "find", "grep"]
  },
  {
    "name": "ops",
    "model": "openai/gpt-4o",
    "systemPrompt": "You manage infrastructure and deployments.",
    "tools": ["bash", "read"]
  }
]

Each squad member gets its own workspace, session history, and set of tools. Route messages to the right squad member through Messaging Apps or by name in the Chat API.

What’s next

Tools

Learn about each tool and how workspace sandboxing works.

AI Providers

Set up API keys for Anthropic, OpenAI, and Google.

Desktop

Deploy and manage squad members from the desktop app or CLI.

Configuration

Squad member settings, the data directory layout, and standalone HQ flags.

Getting Started

Core Concepts

Guides

Reference

Help

What is a squad member?

Squad member configuration

Available models

Anthropic

OpenAI

Google

Moonshot (Kimi)

OpenRouter

Available tools

Fallback models

Workspace

Lifecycle

Sessions

Multiple squad members

What’s next

Tools

AI Providers

Desktop

Configuration

​What is a squad member?

​Squad member configuration

​Available models

Anthropic

OpenAI

Google

Moonshot (Kimi)

OpenRouter

​Available tools

​Fallback models

​Workspace

​Lifecycle

​Sessions

​Multiple squad members

​What’s next

Tools

AI Providers

Desktop

Configuration

What is a squad member?

Squad member configuration

Available models

Available tools

Fallback models

Workspace

Lifecycle

Sessions

Multiple squad members

What’s next