Creating Squads¶

Create a squad by choosing a template or configuring agents from scratch. The four-step wizard walks you through basic info, workspace selection, agent configuration, and a final review.

Using Templates¶

The fastest way to get started is with a pre-built template. Open the Squad page from the sidebar and click Create Squad to see the template gallery.

Built-in Templates¶

Click a template card to preview its agents and their configurations before creating the squad.

Custom Templates¶

You can save any squad as a reusable template. Once you've fine-tuned a squad's configuration, use the Save as template action to make it available in the gallery for future use.

The Setup Wizard¶

Step 1: Basic Info¶

Enter a name and an optional description for your squad. Choose a clear name that identifies the squad's purpose (e.g., "Auth Module Squad", "Blog Content Squad").

Step 2: Workspace¶

Select a workspace directory where the squad will store its files. The wizard validates that:

• The path is absolute
• The path exists and is writable
• No other squad is using the same directory
• The path does not reach the application's own data directory

The workspace is organized with subdirectories for plans, tasks, agent files, and metadata.

A workspace at, inside, or above the application data directory is refused, and so is one that reaches the legacy ~/.backend-ai-go directory or the sockets directory. That directory holds your settings, API access keys, stored credentials, and saved squads, so a workspace overlapping it would give every squad agent read-write access to all of it, and deleting the squad without Keep workspace directory would remove it. Choosing your home directory is refused for the same reason; a project directory inside it is fine. This check runs again each time the workspace is browsed or searched afterward, so a squad whose workspace was recorded before the check existed still refuses to serve an application-owned directory rather than exposing it.

Step 3: Agents¶

Configure the agents in your squad. You can:

• Start from a template — Agents are pre-populated from the selected template
• Add agents manually — Click Add Agent and choose a role
• Import from Profile — Import an agent configuration from the Cowork agent profile marketplace

For each agent, configure:

Agent Roles¶

• Planner — Coordinates the squad. Analyzes requests, creates plans, assigns tasks, and tracks progress. Designate exactly one planner per squad.

• Developer — Writes and modifies code. Has access to filesystem tools for reading and writing project files.

• Reviewer — Reviews output for quality, security, and correctness. Typically has read-only access.

• Writer — Creates documentation, articles, and other written content.

• Custom — Define a role that doesn't fit the predefined categories. Enter a custom role name and tailor the system prompt.

Step 4: Review¶

Review the complete squad configuration:

• Squad name and description
• Workspace path
• Agent list with roles and tool access
• Designated planner agent

Click Create Squad to finalize. The workspace directory is created and initialized automatically.

If a required field is still missing (for example, the workspace directory when you jumped straight to agent configuration with Customize), the wizard returns to the step that needs attention instead of submitting. If creation fails on the backend, the error appears inside the dialog and your configuration, including every agent you edited, stays in place so you can fix the problem and try again.

Managing Squads¶

Editing a Squad¶

Open a squad and modify its configuration — rename it, add or remove agents, change system prompts, or adjust tool access. Changes take effect for the next execution.

Changing the model for every agent¶

A squad usually has several agents, each with its own model. To switch a whole squad to a different model in one step, use Set model for all agents. It is available in the squad detail page header's More actions (⋯) menu and on the Set model action of each squad card.

The dialog lets you:

• Pick the new model once with the model selector.
• Review the per-agent list, where every agent is included by default. Toggle an agent off to leave its current model untouched.
• Confirm to apply the change. A single atomic update replaces the preferred model for every selected agent in that squad only — it never affects agents in any other squad.

The Apply button stays disabled until you pick a model and keep at least one agent selected. A notification reports how many agents were updated.

Deleting a Squad¶

When deleting a squad, you can choose to:

• Keep workspace directory — Removes the squad from the app but preserves all files on disk
• Delete everything — Removes the squad and its workspace directory

Importing from a Workspace¶

Import from Workspace on the Squads tab (also offered as a shortcut on the Overview tab) opens a folder picker and then does one of two things, depending on what the folder holds.

• The folder has a .squad-config.json manifest. This is the file written when you delete a squad with Keep workspace directory selected. The wizard opens in restore mode, pre-filled with the squad's name, description, and agents, so you can review the configuration and confirm to recreate the squad entry.
• The folder has no manifest. Any other directory, including an existing squad's workspace and a fresh project folder, falls into this case. The wizard opens in create mode with that folder already selected as the workspace, so you can build a new squad around code you already have.

If a manifest is present but cannot be read (truncated, invalid JSON, or written by an unsupported schema version), the wizard does not open and the error is reported instead. Fix or remove the file and try again.