How to add an agent

This guide shows how to add an agent from the Sidekicks window, with the "Add an agent" assistant, wherever the agent runs: on this computer, in a Docker container or in an sbx sandbox. It assumes the agent's program speaks ACP (for mm: the -acp argument).

Steps

Open the assistant: ＋ Add my first agent on the welcome screen, ＋ Add an agent under the agents list, or ⇧⌘N (Ctrl+Shift+N on Linux and Windows).
Who is it? Fill in Name shown (e.g. Garfield (translator)). Name used with @ follows it; change it if you want a shorter one (lowercase letters, digits, - and _, starting with a letter). The icon and the description are optional.
Where does it run? Choose the environment, then fill in what it asks for (see below).
How is it started? Fill in Program, Arguments (on one line, as in a terminal; quotes group words) and Agent's folder. The folder is created when it does not exist.
Click Add the agent. Its direct conversation opens once the configuration is reloaded.

When the agent cannot be added (a name already used, for instance), the assistant says why and writes nothing.

Variants

On this computer: the program runs here, in the agent's folder. If Sidekicks was opened from the Finder and does not find the program, write its full path (which mm in a terminal gives it). Sidekicks reads your shell's PATH at startup, so this is rarely needed.
In a Docker container: give the Container name. The container must be running, with the agent's folder mounted at the same path, and contain the program: see How to run an agent in a Docker container. Sidekicks starts the agent with docker exec -i <container> <program> <arguments>.
In an sbx sandbox: give the Sandbox name. The sandbox must exist, with the agent's folder at the same path: see How to run an agent in an sbx sandbox. Sidekicks starts the agent with sbx exec -i <sandbox> <program> <arguments>.
Options the assistant does not ask for (env, afterStop, a different workspacePath): add the agent with the assistant, then complete its entry in Settings.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# How to add an agent

This guide shows how to add an agent from the Sidekicks window, with the "Add an agent" assistant, wherever the agent runs: on this computer, in a Docker container or in an sbx sandbox. It assumes the agent's program speaks ACP (for `mm`: the `-acp` argument).

## Steps

1. Open the assistant: **＋ Add my first agent** on the welcome screen, **＋ Add an agent** under the agents list, or **⇧⌘N** (Ctrl+Shift+N on Linux and Windows).
2. **Who is it?** Fill in **Name shown** (e.g. `Garfield (translator)`). **Name used with @** follows it; change it if you want a shorter one (lowercase letters, digits, `-` and `_`, starting with a letter). The icon and the description are optional.
3. **Where does it run?** Choose the environment, then fill in what it asks for (see below).
4. **How is it started?** Fill in **Program**, **Arguments** (on one line, as in a terminal; quotes group words) and **Agent's folder**. The folder is created when it does not exist.
5. Click **Add the agent**. Its direct conversation opens once the configuration is reloaded.

When the agent cannot be added (a name already used, for instance), the assistant says why and writes nothing.

## Variants

- **On this computer**: the program runs here, in the agent's folder. If Sidekicks was opened from the Finder and does not find the program, write its full path (`which mm` in a terminal gives it). Sidekicks reads your shell's `PATH` at startup, so this is rarely needed.
- **In a Docker container**: give the **Container name**. The container must be running, with the agent's folder mounted at the same path, and contain the program: see [How to run an agent in a Docker container](run-an-agent-in-docker.md). Sidekicks starts the agent with `docker exec -i <container> <program> <arguments>`.
- **In an sbx sandbox**: give the **Sandbox name**. The sandbox must exist, with the agent's folder at the same path: see [How to run an agent in an sbx sandbox](run-an-agent-in-a-sandbox.md). Sidekicks starts the agent with `sbx exec -i <sandbox> <program> <arguments>`.
- **Options the assistant does not ask for** (`env`, `afterStop`, a different `workspacePath`): add the agent with the assistant, then complete its entry in **Settings**.

## See also

- What the assistant writes: [The configuration file](../reference/configuration.md)
- [How to edit or switch the configuration](edit-or-switch-the-configuration.md)
- [Tutorial: your first agent, without writing any configuration](../tutorials/your-first-agent.md)