# oap agent

> oap agent: Manage and run AgentClass resources. Every subcommand, flag, and example, generated from the CLI.

Source: https://openap.org/docs/oap-agent

Manage and run AgentClass resources

## `oap agent apply <path>`

Server-side apply an AgentClass YAML

## `oap agent authz <name>`

Show the effective, ordered authz hook pipeline for an AgentClass

## `oap agent chat <agent-class>`

Drive an AgentClass agent through an interactive full-screen TUI

Flags:

```text
--budget-duration duration  Per-session max wall-time (default "0s")
--budget-tokens int64       Per-session max tokens
--budget-turns int32        Per-session max turns
--name string               Session name (default: <agent>-<short-uuid>)
```

## `oap agent delete <name>`

Delete an AgentClass

## `oap agent grant-start <agent> <email>`

Let a non-member start sessions of this agent (writes agentclass#starter)

## `oap agent inspect <path-to-oap-or-folder>`

Print the manifest, questions, requirements, and digest of an agent container (.oap)

Flags:

```text
--readme  Print the bundle's README.md (raw markdown) instead of the summary
```

## `oap agent install <ref-or-path>`

Install a .oap agent container onto the cluster.

&lt;ref-or-path&gt; is either a local .oap file / folder-source directory, or
an OCI reference ("host[:port]/name[:tag]") pulled from a registry.

--verify checks the ref's cosign-format signature against --key BEFORE
anything is pulled or installed (see `oap agent verify`); a failed check
installs nothing and exits non-zero. --values/--set answer the bundle's
install questions non-interactively; any question still unanswered when
stdin isn't a TTY is a hard error naming it.

Registry credentials are read from OAP_REGISTRY_USERNAME,
OAP_REGISTRY_PASSWORD and OAP_REGISTRY_HOST (set all three, or none
for anonymous access). They are only sent to OAP_REGISTRY_HOST (e.g.
ghcr.io or localhost:5000). push and sign refuse a &lt;ref&gt; on any other host;
pull, verify and install access it anonymously. Over --plain-http they are
sent only to loopback unless OAP_REGISTRY_PLAIN_HTTP_CREDENTIALS=true.

Flags:

```text
--adopt stringSlice             Adopt a pre-existing object this install would otherwise refuse to overwrite. Bare --adopt adopts every conflicting object except Secrets; --adopt=Kind/Name (repeatable) adopts exactly that object and is the only way to adopt a Secret. An adopted object's spec is overwritten with the bundle's, and oap agent uninstall will delete it.
--build-context stringToString  Supply a named build context path (name=/path); repeatable
--build-missing                 Build any referenced image that isn't available, without prompting
--build-secret stringToString   Supply a build secret value (name=env:VAR or name=value); repeatable
--fit-resources                 Answer capacity clamp questions from their suggested defaults instead of prompting (auto-fit to this cluster's ceiling)
--image-registry string         Registry to push built images to for clusters with no local image-load path (default: inferred from the installed operator image, then from the cluster's cloud). On such a cluster a tag that already exists in the registry is reused as-is and NOT rebuilt, even if the bundle's sources changed — pass --rebuild-images to force a rebuild and push over that tag
--key string                    Path to a PEM-encoded ECDSA public key (PKIX) to verify against (required with --verify)
--name string                   Install instance name — prefixes every bundled CR's name and is stamped as the install label (default: the bundled AgentClass's own name)
--no-build                      Never build; fail if a referenced image isn't available
--plain-http                    Use plain HTTP (no TLS) to reach the registry — for loopback/dev registries
--platform string               Target platform for built images (default: the cluster's node arch when pushing to a registry, else the docker host arch)
--rebuild-images                Rebuild referenced images even if already present
--set stringToString            Override a single question's answer (name=value); repeatable
--values string                 Path to a YAML file seeding question answers
--verify                        Verify the ref's cosign-format signature against --key before pulling anything (fails closed; ignored for a local path)
--vm-ssh-key string             Path to the oap-desktop VM SSH private key (default: auto-discover; overrides OAP_DESKTOP_SSH_KEY)
```

## `oap agent lint <path-to-oap-or-folder>`

Validate an agent container (.oap or folder source): manifest, questions, binding targets, and any bundled AgentUI

## `oap agent list`

List AgentClass CRs

## `oap agent list-starters <agent>`

List the standing starter grants on this agent

## `oap agent logs <agent-class>`

Convenience wrapper for the common debugging case: when an AgentClass has
exactly one in-flight (non-terminal) AgentSession, dump or follow its
memory turns.

If zero or more than one matching session exists, the command prints
the candidates and exits non-zero — fall back to `oap session logs &lt;name&gt;` to
pick one explicitly.

By default Failed/Succeeded sessions are excluded so that "the current
session" is unambiguous. Pass --include-done to consider every session
that references the AgentClass.

--follow-live keeps the channel-bound debug loop alive across sessions
indefinitely. "Live" here means actively making progress — phase
Running, Pending, or AwaitingApproval. Idle channel-attached sessions
(dormant between user messages) are intentionally excluded so the
loop doesn't sit on a thread that isn't doing anything.
  * 0 active sessions → poll quietly until one appears.
  * exactly 1 active → stream it; when it transitions out of an
    active phase (becomes Idle, Failed, or Succeeded), return to the
    poll loop and pick up the next active session for the same class.
  * more than 1 active → print the candidate list, then KEEP polling.
    When the set collapses back to a single active session, switch
    to streaming it. The list is only re-printed when the set
    changes, so the loop stays quiet between updates.
The only exit paths are Ctrl-C and the --timeout cap.

Flags:

```text
--follow-live       Watch for live sessions of the AgentClass indefinitely; stream when exactly one exists, print + refresh the candidate list when more than one exists, switch back to streaming when it collapses to one.
--include-done      Include Failed and Succeeded sessions when picking the candidate
--timeout duration  Client-side cap when --follow is set (default "30m0s")
-f, --follow        Keep streaming until the session is terminal or canceled
```

## `oap agent package <agentclass-name-or-folder>`

Author a .oap agent container from a folder source or a live AgentClass

Flags:

```text
-o, --output string  Output path for the .oap ('-' for stdout; default: <agent-name>.oap in the current directory)
```

## `oap agent pull <ref>`

Pull a .oap agent container from an OCI registry.

&lt;ref&gt; is an OCI reference ("host[:port]/name[:tag]").

--verify checks ref's cosign-format signature against --key before
writing anything locally (see `oap agent verify`); a failed check writes
nothing and exits non-zero.

Registry credentials are read from OAP_REGISTRY_USERNAME,
OAP_REGISTRY_PASSWORD and OAP_REGISTRY_HOST (set all three, or none
for anonymous access). They are only sent to OAP_REGISTRY_HOST (e.g.
ghcr.io or localhost:5000). push and sign refuse a &lt;ref&gt; on any other host;
pull, verify and install access it anonymously. Over --plain-http they are
sent only to loopback unless OAP_REGISTRY_PLAIN_HTTP_CREDENTIALS=true.

Flags:

```text
--key string         Path to a PEM-encoded ECDSA public key (PKIX) to verify against (required with --verify)
--plain-http         Use plain HTTP (no TLS) to reach the registry — for loopback/dev registries
--verify             Verify ref's cosign-format signature against --key before writing anything locally (fails closed)
-o, --output string  Output path for the pulled .oap ('-' for stdout; default: <repo-basename>.oap in the current directory)
```

## `oap agent push <ref> <path>`

Push a packed .oap agent container to an OCI registry.

&lt;path&gt; is the path to a .oap produced by `oap agent package` ('-' reads it from stdin).
&lt;ref&gt; is an OCI reference ("host[:port]/name[:tag]").

Registry credentials are read from OAP_REGISTRY_USERNAME,
OAP_REGISTRY_PASSWORD and OAP_REGISTRY_HOST (set all three, or none
for anonymous access). They are only sent to OAP_REGISTRY_HOST (e.g.
ghcr.io or localhost:5000). push and sign refuse a &lt;ref&gt; on any other host;
pull, verify and install access it anonymously. Over --plain-http they are
sent only to loopback unless OAP_REGISTRY_PLAIN_HTTP_CREDENTIALS=true.

Flags:

```text
--plain-http  Use plain HTTP (no TLS) to reach the registry — for loopback/dev registries
```

## `oap agent put-key <agent-class>`

Read an existing AgentClass, follow its spec.model.apiKey SecretKeyRef,
and create-or-update the underlying Secret with the supplied key bytes.
Lets you keep AgentClass YAML in git without embedding secrets.

The AgentClass must have spec.model.apiKey.name and spec.model.apiKey.key set.

Exactly one of --from-literal, --from-env, --from-env-file, --from-file,
--from-stdin must be supplied.

Example:
  oap agent put-key my-agent --from-env-file .env:ANTHROPIC_API_KEY

Flags:

```text
--from-env string       Read key from the named environment variable (e.g. ANTHROPIC_API_KEY)
--from-env-file string  Read key from a .env file: PATH:KEY (note: PATH may not contain a colon)
--from-file string      Read key from a file path
--from-literal string   Key value as a literal string (avoid in shell history)
--from-stdin            Read key from stdin (single line; trailing newline trimmed)
```

## `oap agent revoke-start <agent> <email>`

Revoke a non-member's standing to start sessions of this agent

## `oap agent run <agent-class>`

Apply a session against an AgentClass and live-stream memory turns

Flags:

```text
--budget-duration duration  Per-session max wall-time (default "0s")
--budget-tokens int64       Per-session max tokens
--budget-turns int32        Per-session max turns
--cleanup-on-cancel         Delete session on Ctrl-C
--name string               Session name (default: <agent>-<short-uuid>)
--no-tail                   Apply + exit; don't stream
--prompt string             Inline prompt (conflicts with --prompt-file)
--prompt-file string        Read prompt from file (or '-' for stdin)
--timeout duration          Client-side cap for the entire run (default "30m0s")
```

## `oap agent sessions [<class-name>]`

List AgentSession CRs, optionally filtered by class

Flags:

```text
--include-subagents  Include delegated child sessions (those with a parent). Hidden by default: one delegating turn can create a session per call.
```

## `oap agent setup-identity <agentclass>`

Read the AgentClass spec; for each ToolBundle.toolspecs[*] and
MCPServers[*].ref, look up its credential requirements and run the
appropriate provider flow. Skips credentials that are already set up
unless --force.

If the AgentIdentity (spec.agentIdentity, or --identity override) does
not exist, prompts to create it.

--only &lt;prefix&gt;:&lt;name&gt;    run setup for one entity only (e.g. --only mcp:linear)
--refresh &lt;credential&gt;    re-run setup for just one credential by name, the name
                          shown in the "already set up: &lt;name&gt;" line, forcing past
                          the idempotency check (e.g. --refresh tailscale-authkey);
                          shows a "did you mean?" on an unknown name
--identity &lt;name&gt;         override AgentClass.spec.agentIdentity
--force                   re-run flows even when the credential is already set up

Flags:

```text
--force            Re-run flows even when credential is already set up
--identity string  Override AgentClass.spec.agentIdentity
--non-interactive  Never prompt: verify credentials that are already provisioned and fail on any that are not
--only string      Run setup for one entity only (e.g. mcp:linear)
--refresh string   Re-run setup for just one credential by name (the name shown in 'already set up: <name>'), forcing past the idempotency check (e.g. --refresh tailscale-authkey)
```

## `oap agent show <name>`

Show details of an AgentClass

## `oap agent sign <ref>`

Sign a pushed .oap agent container in its OCI registry.

&lt;ref&gt; is an OCI reference ("host[:port]/name[:tag]") that must already
have been pushed (see `oap agent push`). --key is a PEM-encoded ECDSA
private key (PKCS#8 or SEC1).

Registry credentials are read from OAP_REGISTRY_USERNAME,
OAP_REGISTRY_PASSWORD and OAP_REGISTRY_HOST (set all three, or none
for anonymous access). They are only sent to OAP_REGISTRY_HOST (e.g.
ghcr.io or localhost:5000). push and sign refuse a &lt;ref&gt; on any other host;
pull, verify and install access it anonymously. Over --plain-http they are
sent only to loopback unless OAP_REGISTRY_PLAIN_HTTP_CREDENTIALS=true.

Flags:

```text
--key string  Path to a PEM-encoded ECDSA private key (PKCS#8 or SEC1) to sign with (required)
--plain-http  Use plain HTTP (no TLS) to reach the registry — for loopback/dev registries
```

## `oap agent uninstall <name>`

Remove every resource a matching `oap agent install` created: every
CR/Secret/ConfigMap carrying the install label &lt;name&gt; (app.kubernetes.io/instance
and agentprimitives.authzed.com/oap-install). A cluster dependency the install
only ADOPTED (a pre-existing, pin-compatible shared SpiceboxToolkit/etc. another
install also depends on) never carries the install label and is left untouched.

## `oap agent verify <ref>`

Verify a pushed .oap agent container's signature in its OCI registry.

&lt;ref&gt; is an OCI reference ("host[:port]/name[:tag]"). --key is the
PEM-encoded ECDSA public key (PKIX/SubjectPublicKeyInfo) matching the
private key `oap agent sign` used. Exits non-zero if no valid signature
is found.

Registry credentials are read from OAP_REGISTRY_USERNAME,
OAP_REGISTRY_PASSWORD and OAP_REGISTRY_HOST (set all three, or none
for anonymous access). They are only sent to OAP_REGISTRY_HOST (e.g.
ghcr.io or localhost:5000). push and sign refuse a &lt;ref&gt; on any other host;
pull, verify and install access it anonymously. Over --plain-http they are
sent only to loopback unless OAP_REGISTRY_PLAIN_HTTP_CREDENTIALS=true.

Flags:

```text
--key string  Path to a PEM-encoded ECDSA public key (PKIX) to verify against (required)
--plain-http  Use plain HTTP (no TLS) to reach the registry — for loopback/dev registries
```
