Operating ocx

ocx supports local configuration and named live management workflows. Coverage is per task: provider edits, account selection, model visibility, routing reads, client integration controls and diagnostics have different transports and limits. A shared API prefix does not prove that every dashboard action has a CLI equivalent.

This skill is for operating a proxy. AGENTS_INSTALL.md covers installation and operating consent; the repository AGENTS.md covers code changes.

Find the task offline

Start at the smallest useful level; no running proxy is needed for help:

ocx help                         # compact root
ocx help models                  # family and declared children
ocx help models preset show      # exact leaf, when declared
ocx help --all                   # full top-level reference, when needed

Then read only the matching task chapter. For example, use providers/models for catalog work or Lab for local evidence. Use ocx help <family> <leaf> or appended --help, not a trailing bare help after nested operands. Missing detail can fall back to family help; it is not proof that a runtime operation is absent.

For a route you already know, an optional lookup is:

ocx capabilities --route '/api/providers/{provider}/model-costs' --json

This matches the declared path template, not a concrete provider URL or HTTP method. Exit 4 means no declaration matched. Full ocx capabilities --json and --mutating-only --json are useful for broad inventories, not mandatory preflight. Declarations describe the installed CLI; actual handlers remain the grammar authority.

Choose a workflow

Start with the named read or preview, then follow its recipe. Help is offline; the target column describes execution. A listed write still needs authority for that task, and read-oriented probes can contact upstream services.

Task domain	Start	Execution target	Verify the result
Lifecycle	ocx status --json	Local runtime	Compare readiness, runtime identity and version; diagnosis
Providers and models	ocx provider snapshot --json	Live management; local authoring is separate	Read saved state and catalog disposition; provider edits, model identities
Accounts	ocx account list --json	Live management	Read active/selected state; quota is opt-in and can probe upstream; pool policy, per-key quota
Agents and routing	ocx route policy list --json	Live management; v2 distinguishes local and live	Inspect revision, saved overrides and apply outcome; routing edits, runtime settings
Integrations	ocx help integration	Selected runtime and its client files	Preview before applying; inspect refusals and ownership; file integrations
Observation and maintenance	ocx logs filter --help	Live management; connected usage is self-scoped	Retain window, filter and incomplete/partial facts; filtered reads, companion totals
Access and remote	ocx connect status --json	Local connection; management runs on its serving host	Separate connection health, key scope and revocation; remote targeting, private key handoff
Lab	ocx help lab	Local evidence; explicit probes and automation have effects	Inspect evidence and export/probe limits; Lab workflow

These are task entry points, not a count of GUI parity. Native window focus, browser presentation and session-only actions retain their own interfaces. Grant inspection does not authorize grant consumption; persisted local Desktop export does not export an unsaved dashboard draft.

Before live management work

1. ocx ready --json checks readiness (ready, pending, failed, unreachable).
2. ocx status --json checks the target and versionSkew.relation. unknown is not a confirmed match; a mismatch needs the intended installation resolved.
3. Run the task with --json only when that leaf supports it. ocx doctor rejects it; ocx v2 supports JSON for both local and explicit live targets.

These checks do not require starting a proxy for offline help, local provider configuration, config validation or local Lab inspection. On a connected client, ordinary management commands do not automatically target the hub: perform them on the hub or use its dashboard. See remote targeting.

Inspect both the exit code and receipt. Saved config, runtime application, client file convergence, skipped work and partial completion are different outcomes; read back the relevant setting after a write. Exit 0 also covers previews and intentional no-ops. Management failures normally print stderr prose even with --json; usage codes include 2 and legacy 64 exceptions for capabilities, ready, and resolve. See JSON shapes and failure semantics before scripting recovery.

Observation and explicit-key API tasks

For request/injection follow, timeline exclusions and scoped usage, start with observation recipes. Use versioned log events to reconstruct observed windows; row JSONL cannot express removals. Neither stream guarantees lossless traffic history.

Selected-key model/audio tasks are separate from management calls. They require explicit operator authorization for upstream calls/uploads and a private human terminal handoff for key input. Never collect the key in this agent session, argv or environment, and never substitute an admin/enrolled credential. Read the selected-key and audio recipe before proposing one. Reports are observations, not key-scope/billing certificates.

Consent: one thing you must not do

Do not star the repository on the user's behalf. ocx inspect star reads the status, and that is the entire CLI surface for it. The starring POST requires a dashboard session, so an ordinary admin-token management call cannot perform it. That is not a barrier against a determined local agent; the consent rule still binds every mechanism because it spends their GitHub identity. Do not route around it with gh, a direct HTTP call, or a minted session. If starring would be useful, say so and let the user decide.

The same boundary covers the session-gated /api/codex-prompt writes: read them with ocx inspect codex-prompt, and leave the writes to the dashboard.

Secret-bearing commands

Do not create an access key or start an access-key rotation from an agent session. This covers the create and rotation-start operations under ocx access key, ocx access keys, and ocx api-key, their opencodex equivalents and executable wrappers, and direct POST requests to /api/keys and /api/keys/rotate. Both text and JSON responses contain a one-time plaintext data-plane credential, which can enter the agent transcript. Ask the user to perform that step in a human-operated terminal outside the agent session, configure and verify the replacement, and report only confirmation plus non-secret key/rotation IDs. Never ask for the plaintext key in chat or offer a pipe, redirection, or API workaround to perform the secret-returning step inside the agent session.

ocx hub invite has the same boundary: text and JSON output expose a plaintext pairing grant or a command embedding it. Use the human-operated terminal handoff in recipe 10; never ask for the grant or generated command in chat. Continue non-secret setup and verification normally.

Configuration confirmation is not approval to revoke the existing credential. Identify the existing key ID and obtain separate explicit revocation approval before committing an in-place rotation or removing an old, separately replaced key. An existing explicit approval for that exact revocation remains valid; setup confirmation alone does not supply it. Commit and abort return no plaintext key, but still require authority for their state changes. Follow recipe 5.

Destructive verbs

storage trash restore and storage policy run refuse without --yes (exit 2, nothing sent). storage cleanup without --yes is a preview that exits 0 having mutated nothing — do not treat that 0 as a delete. There is no interactive prompt.

The expected sequence is preview, report, then ask:

ocx storage cleanup --percent 25 --json      # previews; deletes nothing; exits 0

Report the count and bytes from that output and get explicit approval before adding --yes. --mode quarantine (the default) can be undone with storage trash restore; --mode permanent cannot.

Remote hub

Read ocx status on the hub and ocx connect status --json on the client before changing their configuration. Pairing is not required to configure the hub. The optional loopback companion serves inference only, never management calls. A human transfers the invite directly to the joining machine outside this session. Remote credential inputs remain stdin-only (--pairing-code-stdin, --admin-token-stdin), never literal argv or environment values.

Disconnect restores local state but leaves the hub key valid. With explicit revocation authority, revoke while still connected, or have the operator revoke on the hub after disconnection. Do not work around ownership or partial-restore refusals. Remote hub covers the one-port setup, credential handoff, managed rotation and disconnection order.

References

File	Use it for
Management index	declared capabilities in eight task chapters, with routes, flags and mutation notes (generated)
JSON shapes	response envelopes and error shapes
Recipes	copy-paste sequences for real tasks
Failure semantics	exit codes, 503 classes, what to retry
Remote hub	hub/client roles, when pairing is and is not needed, key rotation, disconnection

The generated index routes to eight task chapters. Lab includes local reads, public evidence operations and explicit automation controls; it is not read-only. Read-oriented probes can contact providers, consume quota or refresh caches. Routing-profile writes use explicit file/revision workflows; discovered-model display-name edits use raw upstream IDs, distinct from custom-model editing. Browser presentation and session-only consent actions remain outside agent management authority.

The index and chapters are generated by scripts/generate-ocx-skill-surface.ts. If metadata and execution disagree, check the installed CLI version and the live target before reporting unsupported behavior; do not infer a new flag.