Skip to main content

kule agents

List the agents Kule can run, see what each one's profile opens in the sandbox, and add, try, approve or remove agents of your own.

Synopsis​

kule agents [OPTIONS] [COMMAND]
SubcommandWhat it does
listList the agents, and why the ones that cannot run cannot (the default).
showShow what an agent's profile opens in the sandbox.
registryList the agents of the ACP registry.
addAdd an agent from the ACP registry as a draft profile.
tryRun a profile once in an empty folder and see what the sandbox refused it.
approveLet one of your profiles run, as it stands now.
revokeTake an approval back.
removeTake one of your profiles out of agents.toml.

Description​

Kule runs agents that speak the Agent Client Protocol (ACP). Each agent has a profile: the command that starts it, and what it may open in the sandbox beyond a task's copy (its own state folder, its login, the hosts it needs).

  • Built in: claude-code, codex and gemini.
  • Yours: profiles in agents.toml in Kule's home (~/.kule/agents.toml).
  • From an extension: profiles an approved extension brings.

A profile opens holes in the sandbox, so one of yours runs only once you approve it, and again after any change to it. It may never open the credentials Kule hides, another agent's state, Kule's home, or a whole directory like ~/Documents, and a package it fetches must name one exact version. Profiles never come from a workspace.

See Agents for every profile field and how to sign the built-in agents in.

The usual way to add an agent:

kule agents registry            # find its id
kule agents add qwen-code       # a draft that opens nothing yet
kule agents try qwen-code --apply   # run it once; add what it was refused
kule agents show qwen-code      # read what it would open
kule agents approve qwen-code   # let it run

All subcommands take --home (see global options).

kule agents list​

kule agents list [OPTIONS]
$ kule agents
claude-code      built in
gemini           built in
codex            built in
qwen-code        yours, held: not approved as it stands; review it with `kule agents show qwen-code`, then `kule agents approve qwen-code`

Add your own in ~/.kule/agents.toml (format: kule agents show claude-code).

held: says why one of your agents cannot run now: it is not approved as it stands (never approved, or changed since), its profile opens something a profile may not, or another profile has the same name.

kule agents show​

kule agents show [OPTIONS] <NAME>

Prints the profile as you would approve it, then any warnings.

$ kule agents show codex
[[agent]]  codex
runs              npx -y @agentclientprotocol/codex-acp@2.2.2 -c sandbox_mode="danger-full-access"
writes in ~/      .codex
its login         .codex/auth.json
read-only         .codex/config.toml, .codex/rules, .codex/plugins, .codex/skills, .codex/prompts, .codex/AGENTS.md, .codex/AGENTS.override.md
sees your env     CODEX_HOME
also connects to  https://auth.openai.com, https://chatgpt.com
session mode      agent-full-access

warning: Kule puts your OPENAI_API_KEY into what codex sends to api.openai.com.

warning: codex sees your CODEX_HOME as it is.
LineMeaning
runsThe command that starts the agent over ACP.
writes in ~/Folders and files under your home the agent may write: its own state.
its loginIts sign-in, hidden from every other agent.
read-onlyParts of its state it may read but not change: settings, hooks, plugins, skills, instructions, which would otherwise make it run something the next time you start it outside Kule.
reveals (macOS)Hidden paths it may read on macOS, such as a keychain.
sees your envYour environment variables it sees as they are.
sets envVariables Kule starts it with.
also connects toHTTPS hosts it reaches while it runs, beyond the policy.
session modeThe agent's own mode Kule starts it in, which leaves sandboxing to Kule.
its own home / home of its ownA folder of its own in Kule (see own_home in Agents).
warning:Something to know before you approve, for example a key Kule fills in for it, or state left writable.

The sandbox is not codex's own: sandbox_mode="danger-full-access" turns off codex's sandbox inside Kule's, which is the one that holds.

kule agents registry​

kule agents registry [OPTIONS]

Lists the agents of the public ACP registry, each with its version and how it starts on this system. The list is kept in Kule's home (registry.json); when the registry cannot be reached, the last copy is shown with (the registry could not be reached; as last read).

$ kule agents registry
auggie                 0.36.0     npx -y @augmentcode/auggie@0.36.0 --acp
claude-acp             0.94.0     npx -y @agentclientprotocol/claude-agent-acp@0.94.0
goose                  1.55.0     download, then ./goose
qwen-code              0.25.3     npx -y @qwen-code/qwen-code@0.25.3 --acp --experimental-skills
cursor                 2026.10.18 not for this system
...

kule agents add​

kule agents add [OPTIONS] <ID>

Adds a draft profile from the registry to agents.toml. A draft opens nothing yet: no state folder, no login, no hosts. It is held until you approve it.

$ kule agents add qwen-code
added qwen-code, opening nothing yet; next: kule agents try qwen-code --apply, then kule agents approve qwen-code

For an agent the registry ships as a download, add says which archive to get, its SHA-256, and what to put on your PATH.

kule agents try​

kule agents try [OPTIONS] <NAME>
OptionMeaning
--applyAdd what the trial suggests to the profile. The profile then waits for approval again.

Runs one of your profiles once, in an empty folder, opened no wider than the profile says (up to two minutes), then lists what the sandbox refused it: the folders it wanted to write and the hosts it wanted to reach. That is what its profile should open.

Its output has this shape (what is refused and suggested depends on the agent):

trying qwen-code in an empty folder (up to two minutes)…
it answered: …
refused  file-write-create /Users/you/.qwen/settings.json (node)
refused  connect example-model-api.com:443 (no-rule-lets-it-pass)
suggested state: .qwen
suggested hosts: example-model-api.com
suggested read-only: .qwen/settings.json
added to qwen-code; review it with kule agents show qwen-code, then approve it

suggested read-only names files in its state that would make it run something or follow instructions when it starts; Kule keeps those readable but not writable.

note

try really starts the agent, so it may ask for a sign-in and may use your account with its provider. Linux does not report refused files, so there only hosts are suggested.

kule agents approve​

kule agents approve [OPTIONS] <NAME>

Prints the profile, then approves it as it stands. Any later change to the profile, by hand or by try --apply, holds it again.

$ kule agents approve qwen-code
[[agent]]  qwen-code
runs              npx -y @qwen-code/qwen-code@0.25.3 --acp --experimental-skills
...

approved qwen-code as it stands; a change to it needs approval again

kule agents revoke​

kule agents revoke [OPTIONS] <NAME>
$ kule agents revoke qwen-code
qwen-code is no longer approved

kule agents remove​

kule agents remove [OPTIONS] <NAME>

Removes one of your profiles from agents.toml. Built-in agents cannot be removed.

$ kule agents remove qwen-code
removed qwen-code

Errors and fixes​

MessageWhat to do
kule: no agent nopeCheck the name with kule agents.
kule: no agent nope in the ACP registryCheck the id with kule agents registry.
kule: there is a profile named qwen-code alreadyEdit or remove the existing profile first.
kule: qwen-code has nothing to run on this systemThe registry offers no build for this OS or processor.
kule: no profile qwen-code of yourstry and remove work only on your own profiles, not built-in ones.
held: not approved as it stands; …Read kule agents show NAME, then kule agents approve NAME.

In the app​

Settings → Agents lists every agent with what it opens. Try it runs a draft once and offers what it was refused as checkboxes, so you can leave a telemetry host out; approving works the same way. The first-run screen says which agents can start, and what to install for the others.

See also​