One file, your order
The file is optional. Without it, uuldana-cli uses the agents it finds installed, under the default permission ceiling. Use it to choose the order, add accounts, or set a tighter ceiling. Nothing in it is a default priority: the order of providers is the order uuldana-cli tries them, and installed agents it does not list come after them.
{
"version": 1,
"permissions": {
"approval": "ask_for_risky",
"filesystem": "workspace_write",
"network": "allowed"
},
"cooldown_minutes": 300,
"failover": true,
"providers": [
{ "id": "claude", "label": "claude-work",
"env": { "CLAUDE_CONFIG_DIR": "D:\\accounts\\work" } },
{ "id": "claude", "label": "claude-personal" },
{ "id": "codex", "cooldown_minutes": 120 }
]
}Fields
| Field | Meaning |
|---|---|
version |
Must be 1. |
permissions |
The ceiling for every session. When it is absent altogether the ceiling is ask_for_risky, unrestricted, allowed. When it is present, the fields it leaves out mean the strictest value. |
permissions.approval |
ask_every_action, ask_for_risky or never_ask. |
permissions.filesystem |
read_only, workspace_write or unrestricted. |
permissions.network |
denied or allowed. |
cooldown_minutes |
How long an entry rests after a usage limit when the provider does not say when it resets. Default 300. |
failover |
false keeps a session on its first provider. Default true. Failover also needs at least two entries. |
auto_detect |
false uses only the agents listed in providers. Default true: installed agents that are not listed follow after the listed ones. |
providers |
Entries in priority order. Optional unless auto_detect is false. |
providers[].id |
The id of an agent found on this machine, which is the name of its program without the extension (see uuldana providers), or the id of a manifest. An entry that matches nothing is left out, with a notice. |
providers[].label |
A unique name for the entry. Defaults to the id; give each account of the same provider its own label. |
providers[].env |
Extra environment variables for that provider’s process only. Used to select an account. |
providers[].cooldown_minutes |
Per-entry override of the rest period. |
Which ceiling lets an agent start
For each agent, uuldana-cli learns the permission modes it can run in from its --help, and an entry starts only if one of them stays inside your ceiling. The agent’s own default way of running, with no permission flag, is always one of them: it is assumed to ask about every action and to restrict nothing. That is why the default ceiling, and any ceiling that allows an unrestricted filesystem and the network, starts every agent that was learned. A tighter filesystem needs a mode the help names. No agent’s help lists a flag that blocks network access, so a ceiling with "network": "denied" starts none of them, and the strictest ceiling contains that: write a ceiling that allows the network, or leave permissions out.
For the four help texts recorded as test data, the modes the help lists give these results. They come from the modes, checked by tests; the first two rows were also run on the real agents.
| Ceiling | Agents that can start (of the four recorded) |
|---|---|
ask_for_risky, unrestricted, allowed |
all four |
never_ask, unrestricted, allowed |
all four |
ask_every_action, read_only or workspace_write, allowed |
one: the one whose help names a plan mode |
An agent whose help names no mode that writes only inside the workspace starts under a workspace ceiling only if a more restrictive mode exists, such as a plan mode that blocks edits. The example above, with "filesystem": "workspace_write", is such a case for an agent with a plan mode.
Without a file
With no file, or a file with no providers, the installed agents are used in the order of their ids, none preferred over another. The ceiling is ask_for_risky, unrestricted, allowed, so every agent that was learned can start. Nothing is written until you choose an order with /agent. Then the file is created with the agents you picked, and the ones you did not pick keep being found by themselves.
Choosing the order inside a session
Type /agent on an empty line and press Enter. Pick the agent that works first, then the ones that take over after it. Agents that are installed but not in config.json are listed too, marked as new, and choosing one adds { "id": "..." } to providers.
The order is written back to config.json. Only the order of providers and added entries change, and the file is rewritten as formatted JSON with sorted keys, so hand formatting is not kept. If the file cannot be written, the new order applies to the current session only and a message says so.
If the agent you picked first is not the running one, the work moves to it now, also with "failover": false. Picking an agent that is resting after a usage limit as the first one ends its rest. If the running agent stays first, it keeps running and its screen comes back as it was.
How agents are found
No agent is known by name. uuldana-cli reads the search path (leaving out the operating system’s own folders), takes the console programs it finds, asks each for --help once with stdin closed and five seconds to answer, and learns an agent from the ones whose help describes one: a way to start with a prompt, a way to resume, and permission or model options. On Windows, only programs whose header says console are asked, and the program behind an npm script shim is found by looking inside the package the shim names. A copy of a program with a version in its name next to the program itself counts as the same program.
The answers are kept in programs.json in the data directory, keyed by the program’s path, size and modification time, so a program is asked again only after it changes. Detection never reads authentication files, and none of an agent’s own files. A manifest in the adapters directory next to config.json is read first and wins over what was learned for the same id.
uuldana providers prints what was found and what was learned about each agent. An entry in config.json that matches no agent found on the machine is left out when uuldana-cli picks an entry to run, with a notice.
Native configuration stays native
An adapter launches the real binary with its normal configuration, plugins, skills, MCP servers, and instruction files. It does not pass flags that disable that discovery unless you asked for it. See Plugins, skills & MCP.