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:

--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:

--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.

<ref-or-path> 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.

Flags:

--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 <name> 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:

--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:

-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.

<ref> 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.

Flags:

--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.

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

Flags:

--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:

--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:

--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:

--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 <prefix>:<name> run setup for one entity only (e.g. --only mcp:linear) --identity <name> override AgentClass.spec.agentIdentity --force re-run flows even when the credential is already set up

Flags:

--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)

`oap agent show <name>`

Show details of an AgentClass

`oap agent sign <ref>`

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

<ref> 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).

Flags:

--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 <name> (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.

<ref> 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.

Flags:

--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