Oko
Oko/Docs

Command reference

oko gateway check

Says whether this machine can reach Brama as oko: the route, the bearer, the signing identity and the gateway’s answer.

Invocation#

Command
oko gateway check [--json]

Inputs and options#

  • --json selects structured output.

Output and state effect#

  • Resolves the route from STADO_MODEL_ROUTER_URL or Stado’s service directory for the consumer oko; reads the bearer `oko-model-router#token` through Skarbiec by Oko’s own consumer and the signing secret `oko-model-agent-auth#agent_auth_secret`; sends a bearer-only GET /v1/models, which is not billable and calls no provider, and prints the four facts and a verdict. Exits successfully only when the gateway answered 200.
  • Skarbiec is resolved separately with stado service directory connect skarbiec --consumer oko --json. Oko does not fall back to a local forward marker. The directory consumer is the product oko. The bearer reader is oko-model-router-client, using ~/.stado/oko-model-router-skarbiec-token. The signing-secret reader is oko-model-agent-auth-client, using ~/.stado/oko-model-agent-auth-client-skarbiec-token. Each reader has only its own exact field grant; the model-invocation grant named oko is not widened with vault-read permissions.
  • oko answers the command (oko gateway check). JSON includes credentialFailures: each failed read of the bearer or the signing secret with its item, field, consumer and the refusal. Text output prints the same. An absent bearer alone does not mean the item is absent: the directory route, broker connection or scoped authorization may have failed.
  • JSON includes resolutionFailure when the Brama directory command fails or returns no usable router URL, and status is the gateway's HTTP status, or the transport error when it could not be reached. Text output prints route resolution and the verdict with the same errors. STADO_MODEL_ROUTER_URL overrides only the gateway address: it does not replace the separate Skarbiec route or credential grants.
  • GET /readyz reports serving state, degradation, build, reason, the agent's routes, subscription redemption failures and unroutable accounts under gateway. gateway.agentFailures retains Brama's unroutable rows for Oko's agent, separately from gateway.unroutable account failures. gateway.authenticationFailures retains automatic sign-in failures with account, provider, stage, HTTP status, blocking code and detail. routingReported distinguishes a missing agent observation from an observed route list.
  • gatewayFailure records an attempted readiness request that failed: operation, url, HTTP status when received, detail and the returned body when readable. HTTP error documents are not treated as readiness reports. A valid readiness document returned with HTTP 503 remains visible alongside that HTTP failure. Only an unresolved origin means the request was not asked.
  • diagnostics contains the same lines as text output and Desktop's Model access screen. problems contains observed access failures; an empty list does not prove that a model replies. Desktop keeps credential presence and gateway checks separate from the Task judge panel's recorded model observation. Top-level ready and the check exit status still describe GET /v1/models bearer acceptance only. Run oko tasks judge --probe, or use Probe judge in Desktop, to test the judge's real model request.

Refusals and safe exits#

  • Anything but `check` prints the usage. HTTP 401 means the gateway’s host has not had that vault field registered as oko’s bearer: `stado credentials token mint oko --host <gateway host> --capabilities call:brama#best --audience oko --token-item oko-model-router` is the fleet declaration; a subscription the gateway may serve to oko also carries the tag `brama:agent:oko`.
  • A missing Skarbiec resolver adapter is declared through stado service directory consumer add skarbiec oko --target HOST --capability secret-acquisition. HOST hands out the loopback port its resolver adapter listens on, and the command prints the address it recorded. The resolver observes the change through its normal refresh; no manual restart is needed. This route declaration does not issue or widen a Skarbiec grant. Run gateway check again to verify the actual credential read and gateway response.
  • Provision the bearer reader on the serving host with stado credentials token mint oko-model-router-client --host SERVING_HOST --capabilities read:oko-model-router#token --audience skarbiec --token-file-name oko-model-router-skarbiec-token --json. Provision the separate signer reader with stado credentials token mint oko-model-agent-auth-client --host SERVING_HOST --capabilities read:oko-model-agent-auth#agent_auth_secret --audience skarbiec --token-file-name oko-model-agent-auth-client-skarbiec-token --json. These commands retain a bearer in an owner-only file rather than printing it.
  • For a synchronized caller, deliver each reader with stado credentials token sync CONSUMER --from-host SERVING_HOST --host CALLER_HOST --source-token-file SOURCE_TOKEN_PATH --token-file DESTINATION_TOKEN_PATH --json. Use the source path returned by mint and the reader path above on the caller. Sync verifies the unchanged grant and does not write a vault. A successful sync is not a successful model request: gateway check and oko tasks verify still test the consuming paths.

CLI reference#