Examples

These examples use the public CLI and API/auth surfaces.

Install And Configure

olyx --help

export OLYX_API_KEY=ak_...
export OLYX_BASE_URL=https://app.olyxai.io

olyx inspect
olyx config

Provider secrets stay in your runtime environment. Olyx does not need them for CLI config discovery.

Expected inspect output:

{
  "base_url": "https://app.olyxai.io",
  "api_key_present": true,
  "dry_run": false,
  "secrets_boundary": "customer_environment",
  "core_runtime": {
    "license_path_present": false,
    "policy_pack_path_present": false,
    "key_id_present": false,
    "public_key_present": false
  }
}

Use config to inspect the current policy snapshot:

olyx config

{
  "offline_testing": false,
  "enterprise_compute": {
    "enabled": false,
    "mode": "standard",
    "compute_backend": "ruby",
    "accelerated_primitives": [],
    "runtime_boundary": "olyx_cloud"
  },
  "guardrails": {
    "max_input_length": 10000,
    "pii_threshold": 0.7,
    "injection_block": true,
    "secret_action": "alert"
  },
  "runtime_failover": {
    "preferred_runtime": "cloud",
    "fallback_order": ["cloud"],
    "edge_fallback": {
      "enabled": false,
      "targets": [],
      "fail_closed": false
    },
    "cloud_fallback": {
      "enabled": true,
      "mode": "cloud-primary",
      "requires_redaction": false,
      "require_customer_kms": false,
      "require_admin_approval": false,
      "raw_payloads_allowed": true,
      "provider_secrets_allowed": false
    },
    "data_boundary": "olyx_cloud",
    "fail_closed": false
  },
  "distribution": {
    "project_id": 123,
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "secrets_boundary": "customer_environment",
    "cloud_payloads": true,
    "local_ref_required": false
  },
  "runtime_activation": {
    "url": "/api/v1/runtime/activation",
    "signature_algorithm": "EdDSA",
    "envelope_format": "jws_compact_json",
    "public_key_distribution": "response_keyring"
  }
}

Read this response before sending trace work. It tells the client whether cloud payloads are allowed, whether a local reference is required, and what guardrails should be applied locally.

End-To-End Worker Flow

Standard backend integration:

1. Inspect local config with olyx inspect.
2. Fetch active policy with olyx config.
3. Create a trace envelope before the model call.
4. Send the model request through the Olyx base URL — Olyx routes to the provider and records the step.
5. Complete the trace and optionally queue a replay.

Example:

export OLYX_API_KEY=ak_prod_support_worker...
export OLYX_BASE_URL=https://app.olyxai.io
export PROVIDER_API_KEY=your_key...

olyx inspect
olyx config
olyx trace --metadata '{"environment":"production","service":"support-worker","feature":"ticket-reply"}'

Full Walkthrough

The CLI manages the Olyx control plane. Provider credentials and model calls stay in your environment.

export OLYX_API_KEY=ak_prod_support_worker...
export OLYX_BASE_URL=https://app.olyxai.io   # or your olyx-edge host for enterprise
export PROVIDER_API_KEY=your_key...

# 1. Confirm the CLI can reach the control plane and read project policy.
olyx inspect
olyx config

# 2. Create a trace with safe operational metadata.
olyx trace \
  --metadata '{"environment":"production","service":"support-worker","feature":"ticket-reply"}'

# 3. Make the model request using your own provider credentials.
#    Cloud: call your provider directly. Enterprise: call through olyx-edge (/v1/chat/completions).
#    Provider secrets stay in your environment either way.

# 4. Mark the trace complete when the request finishes.
olyx complete trace_01J6AF...

# 5. Queue a replay if you want to compare behavior later.
olyx replay trace_01J6AF...

Create A Trace

olyx trace --metadata '{"source":"cli","feature":"support"}'

The response includes the trace ID and the active distribution contract:

{
  "id": "trace_01J6AF...",
  "status": "pending",
  "created_at": "2026-06-03T14:12:09Z",
  "revenue": null,
  "distribution": {
    "distribution_channel": "cli",
    "telemetry_mode": "anonymized",
    "payload_storage_mode": "cloud_anonymized",
    "payload_retained": true,
    "replay_execution_mode": "cloud",
    "local_ref": null
  }
}

The same operation through HTTP:

curl "$OLYX_BASE_URL/api/v1/traces" \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trace-create-01J2Z9F7" \
  -d '{
    "metadata": {
      "source": "checkout-worker",
      "environment": "staging",
      "feature": "refund-assistant",
      "routing_tier": "medium"
    }
  }'

Create A Trace With A Local Reference

Use a local reference when your application stores trace payloads outside Olyx Cloud:

olyx trace \
  --metadata '{"source":"worker","feature":"refund-assistant"}' \
  --local-ref "postgres://traces/01J2Z9F7"

local_ref should be opaque to Olyx. It can identify a database row, object-storage key, or internal replay record inside your environment.

Good local references:

postgres://ai_traces/01J2Z9F7
s3://customer-replay-store/prod/trace_01J2Z9F7.json
internal-run:refund-assistant:01J2Z9F7

Avoid local references that contain secrets, emails, raw prompts, or signed URLs.

Complete A Trace

olyx complete trace_01J6AF...

The CLI sends PATCH /api/v1/traces/:id/complete to OLYX_BASE_URL — the same command works against Olyx Cloud and an olyx-edge node. No request body is required. If the work fails or is stopped before completion, use the trace update path instead.

Equivalent HTTP call:

curl "$OLYX_BASE_URL/api/v1/traces/trace_01J6AF.../complete" \
  -X PATCH \
  -H "Authorization: Bearer $OLYX_API_KEY"

Queue A Replay

olyx replay trace_01J6AF...

Replay jobs are asynchronous:

{
  "job_id": "job_01J6AG...",
  "source_trace_id": "trace_01J6AF...",
  "status": "queued"
}

Poll the job through the API:

curl "$OLYX_BASE_URL/api/v1/replay/job_01J6AG..." \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Accept: application/json"

Poll With Backoff

for delay in 1 1 1 2 2 5; do
  curl "$OLYX_BASE_URL/api/v1/replay/job_01J6AG..." \
    -H "Authorization: Bearer $OLYX_API_KEY" \
    -H "Accept: application/json"
  sleep "$delay"
done

Stop polling when the job reaches completed, failed, or canceled.

Example completed replay summary:

{
  "job_id": "job_01J6AG...",
  "source_trace_id": "trace_01J6AF...",
  "status": "completed",
  "summary": {
    "baseline_model": "standard-model",
    "candidate_model": "frontier-model",
    "latency_delta_ms": -120,
    "cost_delta": "0.0008"
  }
}

Anonymized Telemetry Example

For anonymized telemetry, keep operational signal and remove direct identifiers:

olyx trace --metadata '{
  "environment":"production",
  "service":"claims-agent",
  "feature":"claim-review",
  "tenant_id_hash":"sha256:3f7d...",
  "policy_decision":"allowed"
}'

Fields to avoid in anonymized mode:

{
  "customer_email": "person@example.com",
  "prompt": "Full end-user prompt...",
  "completion": "Full model response..."
}

Customer-Managed Payload Example

When project policy requires customer-side payload ownership, keep the full prompt and completion in your own system and send only a stable local reference:

olyx trace \
  --local-ref 's3://customer-private-ai/prod/2026/06/trace_01J6AF.json' \
  --metadata '{"environment":"production","service":"claims-agent","feature":"claim-review"}'

Policy-Aware Validation

Example local input-length check before creating a trace:

const maxInputLength = policy.guardrails?.max_input_length ?? 10000;

if (prompt.length > maxInputLength) {
  throw new Error(`Input exceeds Olyx policy limit of ${maxInputLength} characters`);
}

Example secret action handling:

const secretAction = policy.guardrails?.secret_action ?? 'alert';

if (secretDetected && secretAction === 'block') {
  throw new Error('Request blocked by Olyx secret policy');
}

const safePrompt = secretDetected && secretAction === 'redact'
  ? redactSecrets(prompt)
  : prompt;

Example injection handling:

if (policy.guardrails?.injection_block && injectionDetected) {
  throw new Error('Request blocked by Olyx injection policy');
}

Example metadata for a blocked request:

{
  "metadata": {
    "source": "support-worker",
    "policy_decision": "blocked",
    "policy_reason": "input_length_exceeded",
    "observed_input_length": 12488
  }
}

Error Handling

curl "$OLYX_BASE_URL/api/v1/traces" \
  -H "Authorization: Bearer bad_key" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"source":"cli"}}'

Example error:

{
  "error": "Unauthorized",
  "code": "unauthorized",
  "request_id": "req_..."
}

Recommended handling:

Example retry posture in a worker:

if (response.status === 401 || response.status === 422) {
  throw new Error('Non-retryable Olyx request failure');
}

if (response.status === 429 || response.status >= 500) {
  await retryWithBackoff();
}