Skip to content
Olivares AI docs

Reports the LOCAL launch requirements observed for one provider profile under one transport and isolation, with the checks this read cannot make left explicitly unknown; it starts nothing, mints nothing and authorizes nothing.

GET
/v1/m/sessions/provider-profiles/{ref}/launch-readiness
 
curl --request GET \
  --url 'https://example.com/v1/m/sessions/provider-profiles/example/launch-readiness?transport=stream-json&isolation=native' \
  --header 'Authorization: Bearer <token>'

Reports the LOCAL launch requirements observed for one provider profile under one transport and isolation, with the checks this read cannot make left explicitly unknown; it starts nothing, mints nothing and authorizes nothing.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
ref
required
string

Path parameter ref.

Header Parameters

Section titled “ Header Parameters ”
X-Olivares-Tenant
string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Query Parameters

Section titled “ Query Parameters ”
transport
string
default: stream-json
Allowed values: stream-json remote-control

Transport the requirements are evaluated for; defaults to stream-json. A known value the selected driver does not offer is answered 200 with an unsupported check, not 400.

isolation
string
default: native
Allowed values: native container sandbox

Containment posture the requirements are evaluated for; defaults to native. container and sandbox are accepted values that the native runner reports as unsupported.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

The launch requirements observed for this profile and selection. It is a dated observation, never an authorization and never proof that the provider is authenticated: configuration_state describes LOCAL configuration only, while provider_authentication and launch_authorization are always unknown here and remaining_checks names what the POST still decides.

Media type application/json
object
checks
required

Every requirement dimension, always complete and always in the same order.

Array<object>
object
check
required

The requirement dimension. Every dimension is always reported, so a dominant known cause never hides an unknown one.

string
Allowed values: profile local_environment driver runner program homes auth_source credential_source runtime_credentials
code
required

Closed cause identifier. It carries no path, argument, environment value, credential or raw error: the console renders localized copy and a static documentation link from it.

string
Allowed values: profile_active profile_disabled profile_retired environment_local other_environment environment_unavailable driver_operable driver_not_registered transport_unsupported runner_ready runner_not_configured isolation_unsupported runner_inspection_unavailable program_present program_missing program_not_executable homes_resolved home_unavailable home_changed auth_source_account_home auth_source_managed_injection auth_source_legacy_claude auth_source_required managed_injection_not_applied_for_transport claude_credential_source_configured claude_credential_source_not_configured provider_credential_adapter_configured provider_credential_adapter_not_configured credential_source_not_injected provider_record_bound runtime_credentials_wired runtime_credentials_not_requested runtime_credential_wiring_incomplete runtime_readiness_unavailable inspection_unavailable not_checked_in_this_environment
remediation

Closed identifier of the operator action that would change this verdict; absent when there is nothing to do.

string
Allowed values: review_profile select_local_profile configure_execution_environment configure_provider_driver configure_session_runner configure_provider_program review_profile_homes authorize_auth_source configure_claude_credential_source configure_provider_credential_adapter review_runtime_credential_composition select_supported_selection retry_inspection
state
required

Ready means this LOCAL requirement was checked and met — not that anything is authenticated or authorized. not_configured is a known absence or incompatibility; unsupported is a combination this runtime does not run; unknown is an observation that could not be made and is never rewritten as an absence; not_applicable means the requirement does not belong to this combination and never substitutes for unknown.

string
Allowed values: ready not_configured unsupported unknown not_applicable
configuration_state
required

Aggregate of the LOCAL configuration checks only, by explicit precedence: a known unsupported combination, then a known missing configuration, then uncertainty, and ready only when every applicable requirement is ready. not_applicable is neutral in that aggregation and is therefore not one of its values. provider_authentication and launch_authorization never contribute to it.

string
Allowed values: ready not_configured unsupported unknown
driver
required

The profile’s driver key. The set is open: a driver becomes operable by being registered with the runtime, never by appearing in a list.

string
environment_ref
required

The execution environment that administers this profile.

string
evaluated_environment_ref

The execution environment that answered. Absent when this node has no persistent environment identity, which keeps profiled launches deny-closed.

string
launch_authorization
required
object
code
required
string
Allowed values: evaluated_on_submit
required_permission
required

The permission creating the run requires. Holding it is not checked by this read and this read never grants it.

string
Allowed values: sessions:run:write
state
required

Always unknown: authorization is decided on the POST, with the budget, kill-switch, approval and claim gates that this read is forbidden to consult because consulting them has effects.

string
Allowed values: unknown
observed_at
required
string format: date-time
profile_ref
required
string
profile_state
required
string
Allowed values: active disabled retired
profile_version
required
integer format: int64
provider_authentication
required
object
code
required
string
Allowed values: not_observed_for_this_launch
state
required

Always unknown: this read never contacts a provider, never reads a login file and never reuses another run’s observed authentication state. A valid home is not an authenticated account.

string
Allowed values: unknown
remaining_checks
required

What this read deliberately did NOT decide, because deciding it needs the effects the launch is allowed to have.

Array<string>
Allowed values: workspace_and_template_validation current_launch_authorization claim_admission credential_mint_when_required process_start provider_authentication_and_protocol
selection
required
object
isolation
required
string
Allowed values: native container sandbox
transport
required
string
Allowed values: stream-json remote-control
transport_capabilities
required
object
input
required

Shape of one operator input: a raw NDJSON line for the Claude stream-json child, a turn of text for a driver that owns an RPC protocol, unavailable when the transport bridges no input.

string
Allowed values: line text unavailable unknown
io
required

Whether Olivares bridges the child’s I/O in both directions or manages its lifecycle only. lifecycle_only means the provider relays the conversation: there is no bridged turn console to render.

string
Allowed values: bidirectional lifecycle_only unknown
protocol
required

The wire contract of the child this selection would own. unknown is a real answer: a registered driver that publishes no transport metadata is never assumed to speak another provider’s protocol.

string
Allowed values: claude_stream_json claude_remote_control codex_app_server grok_acp opencode_acp gemini_acp unknown
Example 
{
  "checks": [
    {
      "check": "profile",
      "code": "profile_active",
      "remediation": "review_profile",
      "state": "ready"
    }
  ],
  "configuration_state": "ready",
  "launch_authorization": {
    "code": "evaluated_on_submit",
    "required_permission": "sessions:run:write",
    "state": "unknown"
  },
  "profile_state": "active",
  "provider_authentication": {
    "code": "not_observed_for_this_launch",
    "state": "unknown"
  },
  "remaining_checks": [
    "workspace_and_template_validation"
  ],
  "selection": {
    "isolation": "native",
    "transport": "stream-json"
  },
  "transport_capabilities": {
    "input": "line",
    "io": "bidirectional",
    "protocol": "claude_stream_json"
  }
}

400

Section titled “ 400 ”

Malformed profile reference, unknown or repeated query parameter, or an invalid transport/isolation value

Media type application/json
object
Example generated 
{}

401

Section titled “ 401 ”

Unauthenticated

Media type application/json
object
Example generated 
{}

403

Section titled “ 403 ”

The caller lacks sessions:profile:read; no filesystem or configuration was inspected

Media type application/json
object
Example generated 
{}

404

Section titled “ 404 ”

No such profile in this tenant (a profile of another tenant is indistinguishable from an absent one)

Media type application/json
object
Example generated 
{}

409

Section titled “ 409 ”

The profile changed during the inspection, so the observation straddled two states; it was discarded and must be read again. The body carries the ratified stable identifier profile_changed, so a client detects this conflict by code and never by matching the message text.

Media type application/json
object
error
required
object
code
required

Stable conflict identifier; detect the conflict by this value, never by the message text.

string
Allowed values: profile_changed
message
required

Human-readable explanation. It is localizable and may change; it is not an identifier.

string
Example 
{
  "error": {
    "code": "profile_changed"
  }
}

429

Section titled “ 429 ”

Rate limited

Media type application/json
object
Example generated 
{}

503

Section titled “ 503 ”

The profile store is unavailable, so no requirements were inspected and no document certifies any

Media type application/json
object
Example generated 
{}