Skip to content

Documentation / 1.14.1

Swarms

Have several agents work on one request at the same time, on your computers and models, and get one answer or one change back.

A swarm is several agents working on one request at the same time, each in a chat of its own. An agent is the AI working on its own part of the job, with its own model, tools, and notes. Toskar hands out the parts, watches the agents work, and puts their work together into one answer.

In a split, Toskar splits your request into parts, and each agent does one part. In a race, agents on different models each do the whole request, and Toskar keeps the best result or combines them.

Agents only run at the same time where they really can: on different computers, on different models, or on a model set to run more than one agent at once. With one model on one computer, a swarm runs as one agent and says why. Swarms are off until you ask for one, because they use more of your computers and take longer than a single answer.

Ask for one with Use a swarm in Chat options, by saying use a swarm in your message, or with a profile whose strategy is Swarm. The terminal, VS Code, coding agents, and the API can start one too.

In a chat with a folder, an Admin can give a swarm a task, such as fixing failing tests. Each agent works in its own copy of the folder, and Toskar merges their changes, runs the project's tests, and asks before it puts the change in your folder.

While a swarm works, Chat shows a lane for each agent, with Stop and Open. Each agent's chat is kept, in the chat's project, so you can read and continue it later.

What you need

  • An installed model that calls tools (Choose and manage models).
  • A Member or Admin account. Visitors and the guests of a chat page can't start a swarm (Share Toskar with other people).
  • For agents that really run at once: a second computer (Connect your computers), a second model, or Agents at once raised on a model (below).
  • For a task in a folder: an Admin account, and a folder, ideally one in Git, chosen for the chat or its project (Projects).
  • To change a profile's swarm, or Agents at once: Advanced mode, in Settings.

Split or race

A swarm is like handing a job to a small team instead of one person. Split it when the job has parts that don't depend on each other. Race it when you want a second opinion, or two tries at a hard problem.

QuestionSplitRace
What each agent doesOne part of the request, such as running costs, cold weather, or noiseThe whole request, each on a different model
What you getOne answer, or one change, written from every agent's workThe best answer, or the answers combined. In a folder, the best change
Helps withResearch with several questions in it, and work on separate filesHard questions and fixes where a second try often does better
Doesn't help withA quick question, or a request that can't be split. It runs as one agentOne model. A race needs at least two

A swarm costs more than one answer: every agent reads the request and does its own work, and Toskar merges at the end. It finishes sooner only when the agents really run at the same time. One computer with one model answers one request at a time, so there a swarm runs as one agent, and the line under the answer says: One agent: this computer can't run more than one at a time with this model.

Tip: Auto never picks a swarm, and a swarm profile still answers quick questions directly. A swarm runs only when you ask for one.

Start a swarm in Chat

  1. Open Chat and type your request.
  2. Choose Chat options, and set Use a swarm to Split or Race.
  3. Check that a Swarm chip shows above your message, then send it.
Chat options open above the message box, with Use a swarm set to Split. Above the message, a chip says Swarm: Split, with a button to remove it
The Swarm chip shows that the next message goes to a swarm. Choose × on the chip to change your mind.

Only that message uses a swarm; the next one is answered as usual. You can also say it in the message itself: end it with use a swarm, or with use 3 agents to name how many (2 to 8). Toskar understands this in English.

Make a profile that always uses one

  1. In Settings, turn on Advanced mode.
  2. Open Profiles & Orchestration, and choose Edit on a profile.
  3. Open Strategy and computers, and set Strategy to Swarm.
  4. Choose Split or Race under Mode.
  5. Under Models, add the models the agents use, in order. A race needs at least two, one agent each. A split takes them in turn.
  6. If you like, set the most Agents, Tokens, and Minutes a swarm may use, then choose Save profile.
A profile named Coding swarm being edited. Strategy is Swarm. In its Swarm controls, Mode is Split, the Models are Qwen Coder 7B then Gemma 4 E4B, Agents is 3, Tokens is empty, and Minutes is 20
A profile's swarm: Split, two models, at most 3 agents and 20 minutes. Empty boxes keep the defaults.

Choose models on different computers, or more than one model, so agents can run at the same time. Chats with this profile use a swarm for real work, and still answer a quick question directly.

Watch the agents

While a swarm works, Chat shows a lane for each agent above the answer. Each lane shows the agent's part, the computer and model it runs on, and how it's doing: Queued, Working, Done, Failed, Stopped, or Out of budget. A working agent shows its latest steps, and a finished one a short summary. In a race, the winner says Chosen.

A chat answered by a swarm: above the answer, three agents' lanes, each with its part, its computer and model, Done, a summary of its result, and Open
Three agents split the question across two computers. The lanes fold above the answer when it's done; choose the heading to open them again.
  • Stop under a lane stops that agent alone. The others go on, and the answer uses what it finished.
  • Stop beside the message box stops every agent.
  • Open opens the agent's own chat. It says which agent it is, with a link back to the main chat, and you can read and continue it like any chat.
  • History lists only the chat you started the swarm in. The agents' chats are in its project: on the project's page, that chat has a line such as 3 agents, which opens to them.
The Warmer house project page. Under the chat Compare three heat pumps for a small house, a 3 agents line is open, listing Agent 1: Running costs, Agent 2: Cold weather, and Agent 3: Noise
A project's page folds a swarm's agents under the chat that started it.

A swarm keeps its agents in chats, so it needs a project. When its agents start, a chat that isn't in one moves into a new project named after the request, and the line under the chat's title says so.

Tasks in a folder

In a chat with a folder, a request for work on its files is a task, such as fix the failing tests (Use Toskar in the terminal). A swarm can do a task too, for an Admin, on the web, the desktop app, or in the terminal. Before it plans, Toskar looks at the folder's files, reading only. It gives each agent a part and the files it expects to change, and parts that would change the same files go to one agent.

In a Git folder, each agent works in its own copy, called a worktree, on its own branch. Every copy starts from your folder as it is, including changes you haven't committed and new files Git doesn't ignore. Your branch, your staged changes, and your stashes are never touched.

  1. Each agent does its part in its own copy, and its work is saved on its branch, such as toskar/swarm/7c2e91d4/agent-1.
  2. Toskar merges the branches one at a time. If two agents changed the same lines, a fix-up agent settles it. If it can't, that agent's work is left out, and the lanes name its branch and files.
  3. Toskar runs the project's checks on the merge: go test, cargo test, npm test, pytest, or make test, whichever the project has.
  4. Toskar asks before it puts the change in your folder, unless your profile lets it write files without asking. When the checks failed, it always asks, and the question says so.
  5. The change goes in your folder as uncommitted changes, so you can look it over before you commit it.
A chat titled Fix the failing checkout tests, answered by a split of 2 agents. Each lane shows its branch. Below them: Result on branch toskar/swarm/7c2e91d4/merged, The project's checks passed, and Applied to your folder as uncommitted changes
Under the lanes: the merged branch, how the checks went, and whether the change is in your folder.
  • Nothing is forced. If your folder changed while the agents worked, so the change no longer fits, it isn't applied, and the answer names the branch. Run git merge with that branch in your folder to bring it in.
  • In a race, each agent does the whole task in its own copy, and the checks run in each. An agent whose checks fail can't win over one whose checks pass.
  • A folder that isn't in Git can't be copied safely, so the agents take turns in the folder itself. The answer says: Not a Git folder: the agents worked one after another in it. A race there runs as one agent.
  • The copies are removed when the swarm ends. The branches are kept for 7 days, or until you delete the swarm with the API.

Approve an agent's tools

An agent's tools ask first, as any chat's do. In a task, its changes and commands ask as a task's do, whatever the profile allows in chat. Each question shows in the chat you started the swarm in, under the lanes, and starts with the agent that asks.

Two agents working, each with Stop and Open. Below them, a question from Agent 2: Test a 100% discount, asking to allow Terminal to run go test ./checkout/..., with Allow once, Allow for this agent, and Deny
Allow for this agent covers that agent's chat only. The other agents still ask.
  • Allow once lets this one call run.
  • Allow for this agent lets that tool run for the rest of that agent's chat. It never covers the whole swarm, so another agent's call still asks.
  • A destructive command, such as deleting files, always asks, and doesn't offer Allow for this agent.
  • With nobody there to answer, such as from another app, a call that has to ask is refused.

Limits on a swarm

A swarm has a budget, so it can't run on without end. Set it in the profile's Swarm controls, or per swarm through the API.

BudgetDefaultWhat it limits
AgentsThe profile's Workers, or 4How many agents a swarm uses, 2 to 8
Tokens400,000Everything all the agents read and write together, 10,000 to 4,000,000. A token is about three quarters of a word
Minutes5 for a question, 30 for a taskHow long a swarm may run, 1 to 240
Tool callsAs for a task or a questionHow many tools each agent may use

When a swarm reaches its budget, agents still working stop, and those waiting don't start; their lanes say Out of budget. Toskar then merges what the others finished.

Agents at once on one model

A model on a computer answers one request at a time, so agents that share it take turns. Agents at once lets up to 4 agents use one model at the same time.

  1. In Settings, turn on Advanced mode.
  2. Open Models, then Installed.
  3. Open More actions beside the model, and choose a number under Agents at once.
The Installed models list with the More actions menu open for Gemma 4 E4B. Under Agents at once, 2 is ticked, between 1, 3, and 4
Agents at once is 1 until you raise it. A running model picks up the new number on its next message.
  • Each agent keeps the model's whole context window, so the model needs more memory: about one more context window's worth for each extra agent.
  • Toskar refuses a number that would leave an agent less than 8K of context, or that wouldn't fit your computer's memory, and says which.
  • Agents that share a model each answer a little slower than one agent alone, but together they usually finish sooner.
  • A model on a paired computer runs as many agents as it's set to on that computer.

From the terminal and VS Code

toskarctl chat --swarm sends every message in the chat to a swarm, and --swarm race to a race. While chatting, /swarm sends just the next message. Each agent has a line that updates as it works, then the answer comes. /agents lists the agents, and /open 2 continues agent 2's chat (Use Toskar in the terminal).

In VS Code, @toskar /swarm sends your question to a swarm, and @toskar /swarm race to a race. The chat shows each agent's steps, then the answer, with a summary of the agents and a link to the swarm's chat (Use Toskar in VS Code). From VS Code a swarm answers questions; start a task in a folder from Toskar or the terminal. /swarm comes in the extension's next release after 0.4.0.

Coding agents and other apps

Coding agents, such as Claude Code or Codex, start helpers called subagents, often several at a time. With one model on one computer, they wait for each other. A swarm profile spreads them out instead. Use swarm: and the profile's id as the model name, on any of Toskar's OpenAI and Anthropic formats. The profile's name with dashes between the words works too, such as swarm:coding-swarm for Coding swarm.

The requestWhat Toskar does
Brings the agent's own tools, as subagents' requests doSpread: sends the request as it is to the least busy of the profile's computers and models, and returns the answer unchanged. Requests sent together run at the same time on different ones
Has no toolsRuns a whole swarm on the last message, and answers with the swarm's answer. The agents' progress comes first, as the answer's reasoning

For Claude Code, toskarctl connect claude-code --swarm and a profile point only its subagents at the swarm. Its own model, and its quick background requests, stay as they were, since those have no tools and would each run a whole swarm (Use Toskar in the terminal).

A request with no tools in Anthropic's Messages format gets the agents' progress as a thinking block, then the answer:

curl -s http://127.0.0.1:7331/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "swarm:general-assistant", "max_tokens": 1024, "messages": [{"role": "user", "content": "Plan a three-day trip to Juneau"}]}'

You’ll see something like:

{"content":[{…"thinking":"…","type":"thinking"},{"text":"…Juneau…","type":"text"}],…"model":"swarm:general-assistant",…}

In OpenAI's Responses format, the progress is a reasoning item before the message:

curl -s http://127.0.0.1:7331/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "swarm:general-assistant", "input": "Plan a three-day trip to Juneau"}'

You’ll see something like:

{…"model":"swarm:general-assistant",…"type":"reasoning"},{"content":[{…"text":"…Juneau…","type":"output_text"}]…}

In OpenAI's Chat Completions format, it's the message's reasoning_content (Connect another app through the API). Here, with one model on one computer, the reasoning says why the swarm ran as one agent.

Apps that speak MCP, such as Claude Desktop or Cursor, get a run_swarm tool from Toskar's MCP server. It takes the request, and optionally mode (split or race) and profile. It returns the swarm's answer and a link to its chat:

curl -s http://127.0.0.1:7331/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "run_swarm", "arguments": {"prompt": "Plan a three-day trip to Juneau"}}}'

You’ll see something like:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"…Juneau…\n\nCoordinator chat: … (open it in Toskar at /chat?c=…)","type":"text"}],"isError":false}}

Who can do what, from another computer with a key from API Access:

WhatWho or which key
Start a swarm in any wayA Member or an Admin. A Visitor's key, or a chat page's guest, is refused
A task in a folderAn Admin, on the web, the desktop app, or in the terminal
swarm: requests that bring toolsA key with Drive models directly, for coding agents, as for the agent's own model. A key limited to one profile can't
swarm: requests without tools, and run_swarmA Member or an Admin. A key limited to one profile can name only that profile, and a chat-only key can't, since a swarm saves chats

With the API

Apps that want the lanes use /api/v1/swarms. Start one with your request, and optionally mode, conversation_id (a chat of yours to run it in), and budget (agents, tokens, minutes). Toskar answers at once, while the agents work:

curl -s http://127.0.0.1:7331/api/v1/swarms \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Plan a three-day trip to Juneau: where to stay, what to do, and what to pack", "mode": "split"}'

You’ll see something like:

{"id":"…",…"mode":"split","status":"running",…}

Then read it back by its id. This starts one, waits until it has finished, and reads it. The record has each agent's part, computer, model, status, and summary, and a note when it ran as one agent:

swarm=$(curl -s http://127.0.0.1:7331/api/v1/swarms \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Plan a three-day trip to Juneau"}' | grep -o '"id":"[^"]*"' | head -1 | cut -d '"' -f 4)
until curl -s http://127.0.0.1:7331/api/v1/swarms/$swarm | grep -q finished_at; do sleep 2; done
curl -s http://127.0.0.1:7331/api/v1/swarms/$swarm

You’ll see something like:

{"id":"…",…"status":"done",…"agents":[…],…"finished_at":"…"}

POST /api/v1/swarms/{id}/stop stops every agent, and stopping one agent's chat with POST /api/v1/chat/stop stops that agent alone. GET /api/v1/conversations?swarm_id= lists a swarm's chats. DELETE /api/v1/swarms/{id} deletes a finished swarm's record and the branches it kept; its chats stay. POST /api/v1/chat also takes swarm, split or race, for one message.

On your phone, tablet, TV, car, and watch

The Toskar apps don't show a swarm's lanes yet. Where an app lists your computer's chats, the chat you started a swarm in shows with its answer, like any other answer, and the agents' own chats aren't listed. Start and watch a swarm on the computer: on the web, in the desktop app, in the terminal, or in VS Code.

Limits

  • Agents run at the same time only on different computers, on different models, or on a model with Agents at once above 1. Otherwise a swarm runs as one agent.
  • Use a swarm and use 3 agents in a message are understood in English only.
  • A task in a folder needs an Admin, and is started on the web, the desktop app, or in the terminal.
  • A race needs at least two models, and a race on a task needs a Git folder.
  • The apps on your phone, tablet, TV, car, and watch show a swarm's answer, but not its lanes.

Troubleshooting

What you seeWhat to do
One agent: this computer can't run more than one at a time with this modelPair another computer, add a second model to the profile's swarm, or raise Agents at once on the model
One agent: this request doesn't split into parts that can be done separatelyName the parts in your request, or use a race
One agent: a race needs at least two models to compareAdd a second model under the profile's swarm Models
One agent: a swarm works on a task in a folder, and this task has noneChoose a folder for the chat, or for its project
One agent: a race on a task needs a Git folder, so each agent has its own copyUse a split, or put the folder in Git with git init
Not applied to your folder. To use it, merge the branch with GitIn your folder, run git merge with the branch it names
An agent's changes conflict, so they weren't mergedThey're kept on the branch the line names. Merge it with Git and settle the conflict yourself
Use a swarm isn't in Chat optionsSwarms need a Member or an Admin account
Agents at once, or Edit on a profile, isn't thereTurn on Advanced mode in Settings
A coding agent gets 404 MODEL_NOT_FOUND for a swarm: modelCheck the profile's id or name. Then check that one of the profile's swarm models is installed on a computer that's on
A coding agent gets 403 "this key can't drive a model directly"Give the key Drive models directly, for coding agents, in API Access

These pages describe Toskar 1.14.1. Download 1.14.1 and its release notes ↗ · Need help? Report a bug or request a feature ↗

Something missing or wrong?

Kind

Sent with it: docs 1.14.1. It becomes a public issue in toskar-core.

Swarms · Toskar documentation