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,
    "activation_command": "olyx verify-runtime"
  }
}

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. Keep provider credentials in your own environment.
5. Complete the work and optionally queue 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

If you want one copy-paste flow that mirrors a real worker, use this order:

export OLYX_API_KEY=ak_prod_support_worker...
export OLYX_BASE_URL=https://app.olyxai.io
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"}' \
  --local-ref 'postgres://traces/01J6AF...'

# 3. Run the local provider call in your own environment.
#    Your worker is in any language — Python, Ruby, Node.js, Go, or anything else.
#    Olyx has no runtime dependency on your language or framework.
./your_worker

# 4. Mark the trace complete when the request finishes.
curl https://app.olyxai.io/api/v1/traces/trace_01J6AF.../complete \
  -X PATCH \
  -H "Authorization: Bearer $OLYX_API_KEY"

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

Step 3 is entirely yours. support_worker here is a stand-in for whatever runs your provider call — a Python script, a Ruby service, a Node.js function, a compiled binary, or a shell script. The Olyx CLI has no runtime dependency on the language or framework your worker uses.

Worker Boilerplate

A minimal starting point for support_worker in common languages. Provider credentials come from your environment; no Olyx-specific code belongs inside the worker itself.

import os
from provider_ai import ProviderAI

client = ProviderAI(api_key=os.environ["PROVIDER_API_KEY"])

response = client.chat.completions.create(
    model="your-model",
    messages=[{"role": "user", "content": "Summarize this support ticket: ..."}],
)

print(response.choices[0].message.content)

require "provider_ai"

client = ProviderAI::Client.new(access_token: ENV.fetch("PROVIDER_API_KEY"))

response = client.chat(
  parameters: {
    model: "your-model",
    messages: [{ role: "user", content: "Summarize this support ticket: ..." }],
  }
)

puts response.dig("choices", 0, "message", "content")

import ProviderAI from "provider-ai";

const client = new ProviderAI({ apiKey: process.env.PROVIDER_API_KEY });

const response = await client.chat.completions.create({
  model: "your-model",
  messages: [{ role: "user", content: "Summarize this support ticket: ..." }],
});

console.log(response.choices[0].message.content);

Replace ProviderAI, provider-ai/provider_ai, PROVIDER_API_KEY, and your-model with the actual client library, key, and model your project uses. Provider-specific setup is covered in the model providers guide. Olyx does not wrap, proxy, or intercept the provider call inside the worker.

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 https://app.olyxai.io/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

curl https://app.olyxai.io/api/v1/traces/trace_01J6AF.../complete \
  -X PATCH \
  -H "Authorization: Bearer $OLYX_API_KEY"

The server completes the trace from the recorded steps; no request body is required. If the work fails or is stopped before completion, use the trace update path instead.

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 https://app.olyxai.io/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 https://app.olyxai.io/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
  }
}

Compatibility Endpoint

Existing OpenAI-compatible clients can point at Olyx’s compatibility endpoint.

curl https://app.olyxai.io/api/v1/chat/completions \
  -H "Authorization: Bearer $OLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "frontier-model",
    "messages": [
      { "role": "user", "content": "Translate to French: Hello, world." }
    ]
  }'

Use the CLI route when you want explicit trace and policy-mode discovery. Use the compatibility endpoint when your application already sends OpenAI-style chat-completions requests.

Example minimal response:

{
  "id": "chatcmpl_01J6AG...",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Bonjour, le monde."
      }
    }
  ]
}

Error Handling

curl https://app.olyxai.io/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();
}