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¶

Template	Category	Agents	Best For
Full-Stack Dev Squad	Development	Planner, Frontend Dev, Backend Dev, Code Reviewer	Software development with planning and review
Content Squad	Content	Planner, Writer, Editor, Translator	Article creation, editing, and translation
Research Squad	Research	Planner, Researcher, Analyst, Summarizer	Deep research with analysis and synthesis
Code Review Squad	Review	Planner, Security Reviewer, Performance Reviewer, Style Reviewer	Code review covering security, performance, and style
Documentation Squad	Content	Planner, API Doc Writer, Tutorial Writer, Diagram Creator	Technical documentation with multiple formats

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.

Creating the squad creates the directory and its subdirectories, and writes a test file in logs/. If that fails, the squad is not created, and the error names the path and the reason the operating system gave. Changing a squad's workspace later is checked the same way. With the web UI of a headless server, the check runs on the server, so the workspace has to be a path the server can write. Under the shipped systemd unit that rules out your home directory, and the error names the unit setting involved; see Squad workspaces under systemd.

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.

Workspace Location

Choose a location with enough disk space for the expected output. Each squad's workspace is independent and can be backed up or version-controlled separately.

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:

Setting	Description
Name	Display name for the agent
Role	Planner, Developer, Reviewer, Writer, or Custom
System Prompt	Instructions that define the agent's behavior and expertise
Tools	Which tools the agent can use (files, memory, search, etc.). File tools work inside the squad workspace; see Tools in the Squad Workspace. The tools that run commands or code are listed under Not available in squads with the reason instead of as switches
Settings	Max Tool Rounds (1 to 500, 10 by default), Max Tokens, and the agent's two time limits, LLM response time limit and Task time limit. Each row shows the default for the agent's model. See Per-Agent Time Limits and Defaults by where the model runs
Memory	Enable to give the agent a persistent memory file

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.

Setting each agent's model¶

A squad usually gives its agents different models by role, for example a large model for the planner and a smaller one for the writers. Set agent models in the squad detail page header's More actions (⋯) menu, or Set model on a squad card, opens one dialog where every agent has its own model picker, so you can give several agents different models in one pass.

Each picker shows the model the agent runs on now. Pick another model to change it.
Change all fills every agent's picker with one model. The pickers stay editable, so you can set a different model for one or two agents before you apply.
Default model clears the agent's own model, and the agent then runs on the default agent model from Settings > Models. The option names that model, or says it is not set.
A changed agent is marked Changed, and the apply button counts the changes. It stays disabled while nothing differs from what the squad has.

Applying saves every change to that squad only in one update, and a notification reports how many agents changed. A click outside the dialog with changes not yet applied shakes it instead of closing it, while Cancel discards them. Remote agents (added from a registered remote profile) are not listed, since their model calls run on the remote node.

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.