How to run a test agent without overloading the machine

 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# How to run a test agent without overloading the machine

This guide shows how to start one of the test agents (Alice, Bob, Riker, Garfield) for manual tests, for an ACP client such as Zed, or for a script. It assumes `mm` and llmman are installed (see the [tutorial](../tutorials/first-acp-exchange.md)).

## Start an agent for an ACP client

Always start agents through the script, never with `mm` directly:

```bash
scripts/agents.sh run garfield
```

The agent now serves ACP on stdin/stdout. When it exits, its slot is freed and its model unloaded. A third agent is refused:

```text
agents.sh: 2 agent(s) already running, the limit is 2:
  alice.41211
  bob.41388
```

## Use it from Zed or another ACP client

Declare the script as the agent command, with an absolute path:

```json
"agent_servers": {
  "Garfield (test)": {
    "type": "custom",
    "command": "/path/to/sidekicks/scripts/agents.sh",
    "args": ["run", "garfield"]
  }
}
```

## Pick the right agent

| To test | Agent |
| --- | --- |
| A plain conversation | `alice` (or `bob` as a second agent) |
| Tool calls and permission requests | `riker` |
| Slash commands and skills | `garfield` |

## Check and free memory

```bash
scripts/agents.sh ps              # agents running, models loaded
scripts/agents.sh unload riker    # unload one agent's model, if loaded
scripts/agents.sh unload --all    # unload every loaded model
```

## Variants

- **`mm` is not on `PATH`**: `MM_BIN=/path/to/mm scripts/agents.sh run alice`.
- **Inside a Docker sandbox**: nothing to do; the script finds llmman at `host.docker.internal:17434` when `127.0.0.1:17434` does not answer. Set `LLMMAN_URL` to force an address.
- **Keep the model loaded between runs** (faster repeated tests): `SIDEKICKS_NO_UNLOAD=1 scripts/agents.sh run alice`.
- **A slot stays taken after a crash**: it is freed automatically once its process is gone; if `ps` hangs on "could not lock", remove `.run/agents/.lock`.

## See also

- Every command and variable → [Reference: scripts/agents.sh](../reference/agents-script.md)
- Why two agents at most → [Memory and local models](../explanation/memory-and-local-models.md)