Squad

A squad member is an AI agent in your team. It has a model, instructions and tools. You tell it what to do, and it finds a way to do the work.

What is a squad member?Copy Anchor Link

A squad member has these parts:

When you send a message, the squad member reads it and decides what to do. It uses tools if necessary, and then it replies. It can do many steps without your help.

Squad member configurationCopy Anchor Link

Create a squad member in the Desktop creation form. To change it later, open the squad member and click Configuration.

1. In the sidebar, click + next to Agents.
2. Enter a name. Examine the model and target HQ.
3. To select another model, click Change. Instructions are optional.
4. Open Advanced if you want to change tools, fallback models, or the workspace.
5. Click Create and open chat.

Desktop opens an empty chat. It does not send a message for you.

By default, the form selects all optional tools, and it shows the number of the selected tools. To clear the tools that you do not want, open Advanced. HQ core and inherited plugin capabilities can also be available.

If no eligible model exists, use Add provider. If a check fails, use Retry. See Create your first squad member for setup and recovery steps.

The HQ keeps the configuration of each squad member. A saved configuration looks like this:

{
  "name": "assistant",
  "model": "anthropic/claude-sonnet-5",
  "systemPrompt": "You are a helpful assistant that specializes in research.",
  "tools": ["bash", "read", "write", "edit", "grep", "find", "ls", "web_search"],
  "fallbackModels": ["openai/gpt-5.5", "google/gemini-3.7-flash"]
}

The HQ saves the squad members in ~/.dash/gateway/agents.json. When the HQ starts again, it loads them from this file. For an HQ that Desktop starts, ~/.dash/gateway on this page means ~/.dashsquad/<hq id>. See Data folders.

Create and edit in AndroidCopy Anchor Link

On Agents, tap Create squad member or the plus icon.

1. Enter a Name.
2. Select a Model from the list, or type its ID.
3. Enter the System prompt.
4. Tap Create squad member.

If the model list cannot load, you can still type a model ID. Connect the provider on AI Providers first.

To edit a squad member, open it and tap Edit. Change the model or system prompt, then tap Save changes. You cannot change its name.

To delete it, tap Delete. Type its exact name in the confirmation, then tap Delete. An error stays in the dialog so you can retry.

Available modelsCopy Anchor Link

dashsquad has models from many providers. Set the model field in provider/model format. These models are in the bundled catalogs of the HQ:

The model list in Desktop shows the catalog models of all providers. For each provider that has a key, the HQ also gets the current model list from that provider. Thus the list can have more models than this table. Select a model of a provider that you connected. Refer to AI Providers to connect a provider.

Available toolsCopy Anchor Link

The creation form shows tool groups under Advanced. The form selects all groups by default. Clear a group to remove all of its tools from the agent.

If you clear all groups, the agent has no file, shell or web tools. It can still talk to you.

Some tools are always available. You do not select them:

• load_skill, to load a skill
• task, to keep a list of tasks
• ask_user_question, to ask you a question in the chat
• get_location, to get the location of your device
• save_memory, recall_memory and forget_memory, if memory is on
• agent and send_message, to start and control sub-agents, if sub-agents are on

Refer to Tools for more information about each tool. Refer to Browser for the browser tool.

Fallback modelsCopy Anchor Link

If the primary model fails, the squad member tries the next model in the chain:

{
  "model": "anthropic/claude-sonnet-5",
  "fallbackModels": ["openai/gpt-5.5", "google/gemini-3.7-flash"]
}

The squad member tries the primary model first, then each fallback model in sequence. It goes to the next model only if the error occurs before the model sends output. For example, a provider outage, a rate limit or a model that the HQ cannot find can cause this. If the error occurs after the model starts its reply, the turn fails.

Each model can come from a different provider. Make sure that you connected each provider in the chain. In the creation form, open Advanced to add a fallback model.

WorkspaceCopy Anchor Link

Each squad member has its own workspace directory. The default is <dataDir>/workspaces/<agent-id>, in the data directory of the HQ. The HQ makes this directory when the first conversation starts.

• bash runs commands in the workspace.
• read, write and edit find relative paths from the workspace.

To use your own files, put them in the workspace. To use a different directory, click Browse… under Advanced in the creation form or on the Configuration tab. On the Configuration tab, you can also click Open in Finder or Reset to auto-generated.

LifecycleCopy Anchor Link

A squad member has one of these states:

Open the squad member in Desktop to change its state:

• Click Disable to stop the squad member.
• Click Enable to start a disabled squad member again.
• Click Remove to remove the squad member from the HQ. This button shows only when the squad member is disabled.

You can also remove a squad member on the Squad page (click Manage next to Agents in the sidebar). Click the trash icon on its row, then click Remove in the dialog. For automation, use the Management API.

SessionsCopy Anchor Link

The HQ saves each conversation with a squad member as a session. Session files are JSONL files. The HQ adds each new event to the end of the file, so the files are easy to examine and safe after a crash.

~/.dash/gateway/sessions/<agent-name>/<conversationId>/

When you send a new message, the squad member loads the session history first. Thus it knows all of the conversation: the messages, the tool results and its own replies.

Multiple squad membersCopy Anchor Link

You can run as many squad members as you need. Each squad member is independent: it can have a different model, different instructions and different tools. Deploy each one from Desktop. Their configurations can look like this:

[
  {
    "name": "researcher",
    "model": "anthropic/claude-sonnet-5",
    "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-5",
    "systemPrompt": "You are a senior software engineer. Write clean, tested code.",
    "tools": ["bash", "read", "write", "edit", "find", "grep", "ls"]
  },
  {
    "name": "ops",
    "model": "openai/gpt-5.5",
    "systemPrompt": "You manage infrastructure and deployments.",
    "tools": ["bash", "read"]
  }
]

Each squad member has its own workspace, session history, memory and tools. You can send messages to a squad member from the Desktop, web, iOS and Android apps, or through a chat app such as Telegram.

Messages between squad membersCopy Anchor Link

A squad member can send a message to another squad member on the same HQ. For example, a researcher can send its findings to a writer. The message starts a turn in a chat of the receiver. The two squad members can reply to each other in a thread. For the tools and all the limits, refer to Tools → Squad messages.

A squad message is never your approval. It cannot answer a question for you, run /goal commands or change settings.

Turn messages on or offCopy Anchor Link

By default, each squad member can send messages and accepts messages.

1. In the sidebar, click Manage next to Agents.
2. Open the squad member and click the Configuration tab.
3. Open the Messages card.
4. Select or clear Can message other agents and Accepts messages from other agents.
5. Click Save.

A disabled squad member does not accept messages. A change applies to the next message of the squad member.

Threads in DesktopCopy Anchor Link

In the chat of the receiver, a squad message shows as Message from and the name of the sender. In the chat of the sender, the sent messages show as Sent to and the name of the receiver. Click Thread or Open thread to open the thread panel. The panel shows all the messages in this thread.

In the thread panel, you can do these actions. For a paused thread, Resume and Close thread also show on the paused row in the chat and in Needs you.

• Click Pause thread. The messages wait until you resume the thread.
• Click Resume to continue a paused thread. The thread can then have 12 more messages and 6 more replies back and forth.
• Click Close thread. The HQ does not deliver the messages in the queue of a closed thread. A new message starts a new thread.

The current iOS and Android apps do not show squad messages yet. A newer iOS build adds them.

A thread pauses by itself after 12 messages, or after 6 replies back and forth. Then the chat shows, for example, Paused after 6 replies back and forth between Writer and Researcher. A paused thread also shows in Needs you.

Related pagesCopy Anchor Link