Capabilities
On this page
A capability is a named permission. Gated operations call for a capability before they run; the call proceeds only if the current subject holds it.
kli is fully permissioned by default. The default subject passes every capability
check, so every gated operation runs. There is no interactive approval prompt.
Restriction is configured up front through the capabilities array in
settings.json (see Restricting with settings
below).
Capability vocabulary
Capability names are lowercase strings with a slashed namespace, for example
file/read or manifest/install. The names below make up the vocabulary the
shipped tools and operations draw on.
Tools
| Capability | Gates |
|---|---|
file/read |
The read, find, and search tools. |
file/write |
The write tool. |
file/edit |
The edit tool. |
process/exec |
The bash tool. |
image/eval |
The eval tool, which evaluates Common Lisp in the running image. |
tools/standard | Convenience name for the four file and process capabilities. See Implication rules. |
Extension lifecycle
| Capability | Gates |
|---|---|
manifest/install | Activating an extension (installing its contributions). |
manifest/retract | Deactivating an extension (retracting its contributions). |
image/recode | Replacing an extension's source in place (deactivate then reactivate). |
manifest/install-remote |
Installing a remote extension with /install. |
image/load-dep | A grant in the dependency-load implication chain. No shipped operation checks it directly. |
image/load-native | The native-load grant carried by a remote install. No shipped operation checks it directly. |
Credentials
| Capability | Gates |
|---|---|
auth/register-reference | Recording a credential for a provider. |
auth/resolve-secret | Reading a stored secret value. |
auth/read-metadata | Inspecting the credential store (provider list, reference metadata; never secret values). |
auth/forget-secret | Deleting a stored credential. |
Implication rules
A coarse capability implies finer ones. Granting a capability grants its full closure, computed transitively at subject construction. Holding any capability in the table below grants every capability it implies.
| Capability | Implies |
|---|---|
tools/standard |
file/read, file/write, file/edit, process/exec |
image/recode |
manifest/install, manifest/retract |
manifest/install-remote |
manifest/install, image/eval |
image/load-native |
image/load-dep, image/eval |
image/load-dep |
image/eval |
Implications compose. Granting manifest/install-remote also grants
manifest/install and image/eval; granting image/load-native grants
image/load-dep and, through it, image/eval.
Gated operations
| Operation | Required capability |
|---|---|
| Invoke a tool | Each capability listed in the tool's metadata (the table above). |
| Activate an extension |
manifest/install |
| Deactivate an extension |
manifest/retract |
| Recode an extension |
image/recode (implies manifest/install and manifest/retract) |
Install a remote extension (/install) |
manifest/install-remote |
| Register a credential |
auth/register-reference |
| Resolve a credential |
auth/resolve-secret |
| Inspect the credential store |
auth/read-metadata |
| Forget a credential |
auth/forget-secret |
A gated operation whose capability the subject lacks signals an error and does not run.
Restricting with settings
The capabilities key in settings.json sets the authority of every agent. Its
value is an array of capability name strings.
| Value | Effect |
|---|---|
| Key absent | The default subject applies. Every capability check passes. |
| Array of capability names | The subject holds exactly the implication-closure of those names. Capabilities outside the closure are denied. |
Empty array [] | The subject holds nothing. Every gated operation is denied. |
| Any non-array value | The value is ignored with a warning, and the default subject applies. |
A restricting array denies only gated operations. Operations that check no capability run regardless.
{
"capabilities": ["file/read", "process/exec"]
}
This subject can run the read, find, search, and bash tools. It cannot
write or edit files, evaluate Lisp, change extensions, or read credentials.
Granting tools/standard instead would grant all four file and process
capabilities through the implication rules above.
The capabilities key is read under the active profile overlay like every other
setting; see Settings and
Profiles.