Quick Start

Create your first traced request and replay job in under 5 minutes.

What you’ll set up: CLI verified against your project, active policy loaded and validated, first trace created, replay queued.

Before You Begin

1. Verify Your Setup

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

olyx inspect

Expected output:

{
  "base_url": "https://app.olyxai.io",
  "api_key_present": true,
  "dry_run": false,
  "secrets_boundary": "customer_environment"
}

api_key_present: true and secrets_boundary: customer_environment confirm the CLI is connected and that provider credentials stay in your environment.

2. Configure The Control Plane

olyx config

The config response tells you how the project is allowed to move data:

• whether cloud payloads are allowed
• whether a local reference is required
• whether replay runs in cloud, edge, or is disabled
• which guardrails are active

Validate The Config Response

Before sending any trace work, assert that the policy your client received is one it knows how to handle. Copy this guard into your integration and call it once on startup:

def assert_supported_policy(policy)
  unless policy.dig("distribution", "distribution_channel") == "cli"
    raise "Unsupported distribution channel"
  end

  unless %w[public anonymized customer_managed].include?(
    policy.dig("distribution", "telemetry_mode")
  )
    raise "Unsupported telemetry mode"
  end

  if policy.dig("distribution", "local_ref_required") && !supports_local_ref?
    raise "This project requires customer-side local references"
  end
end

def assert_supported_policy(policy: dict) -> None:
    channel = policy["distribution"]["distribution_channel"]
    if channel != "cli":
        raise ValueError("Unsupported distribution channel")

    telemetry_mode = policy["distribution"]["telemetry_mode"]
    if telemetry_mode not in {"public", "anonymized", "customer_managed"}:
        raise ValueError("Unsupported telemetry mode")

    if policy["distribution"]["local_ref_required"] and not supports_local_ref():
        raise ValueError("This project requires customer-side local references")

function assertSupportedPolicy(policy: OlyxPolicy) {
  if (policy.distribution.distribution_channel !== 'cli') {
    throw new Error('Unsupported distribution channel');
  }

  if (!['public', 'anonymized', 'customer_managed'].includes(policy.distribution.telemetry_mode)) {
    throw new Error('Unsupported telemetry mode');
  }

  if (policy.distribution.local_ref_required && !supportsLocalRef()) {
    throw new Error('This project requires customer-side local references');
  }
}

The same three checks apply in any language: assert distribution_channel, validate telemetry_mode against your supported set, and fail closed if local_ref_required is true but your client cannot satisfy it. Failing closed is intentional — if the project policy has advanced beyond what your client version understands, stopping is safer than silently dropping guardrails. See Policy Schema for the full type definition and field reference.

3. Create The First Trace

olyx trace --metadata '{"source":"quick-start","feature":"first-request"}'

Expected output:

{
  "trace_id": "trace_01J6AF...",
  "status": "open",
  "policy_applied": true
}

Keep the metadata small and use stable identifiers. If your project requires a local reference, pass one that points to your own database row or object store key.

4. Complete The Workflow

When the local request finishes, close the trace through the public API:

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

The completion step is server-driven. It does not require a request body.

5. Queue A Replay

olyx replay trace_01J6AF...

Expected output:

{
  "replay_id": "rpl_01K2BG...",
  "trace_id": "trace_01J6AF...",
  "status": "queued"
}

Use replay when you want to compare routing or model behavior after a policy change. Results appear in the dashboard once the replay job completes.

What To Read Next

• Examples — copyable request and response shapes for common integration patterns.
• Use Cases — deployment patterns for support, agents, and cost-sensitive workloads.
• Governance — review the ledger evidence your traces produce.
• Cost Intelligence — compare spend across routing changes using replay.