Policy Schema

The public policy schema tells CLI clients how a project is allowed to behave. It is intentionally small: enough for local clients to understand telemetry, guardrails, routing intent, and trace boundaries without exposing private deployment internals.

Across cloud deployments, provider secrets remain in the customer environment. Olyx Cloud may retain public or anonymized telemetry according to project policy. For Enterprise private deployments, Olyx Cloud does not store private payloads unless the deployment is explicitly configured to allow that boundary.

Schema Shape

{
  "version": "2026-05-27",
  "project_id": 123,
  "distribution": {},
  "runtime_failover": {},
  "guardrails": {},
  "routing": {},
  "telemetry": {}
}

Policy snapshots are read-only from the CLI. Change project settings in the dashboard or through authenticated API endpoints.

Reading The Schema In Order

A practical client usually reads policy in this order:

1. distribution to decide what data can leave the environment.
2. guardrails to decide what should be blocked, redacted, or alerted.
3. routing to attach tier or intent metadata.
4. telemetry to decide which fields are safe to emit.

Versioning

Policies include a date-based version. Clients should support the versions they were built for and fail closed when a required field has an unknown value.

Recommended client behavior:

The public schema is intentionally additive. Existing fields should remain stable once published.

Distribution

{
  "distribution": {
    "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
  }
}

For Enterprise private deployments, customer_managed values indicate that the private runtime or outbound/on-prem agent owns the payload boundary by default, with cloud retention enabled only when explicitly configured.

Distribution Decision Matrix

If the combination is unknown, the client should stop before creating traces.

Example fail-closed decision:

{
  "distribution": {
    "telemetry_mode": "customer_managed",
    "payload_storage_mode": "customer_managed",
    "local_ref_required": true
  }
}

Guardrails

{
  "guardrails": {
    "max_input_length": 10000,
    "pii_threshold": 0.7,
    "injection_block": true,
    "secret_action": "alert"
  }
}

Secret actions mean:

Guardrail Evaluation Order

Clients should apply lightweight local validation before creating trace work:

1. Confirm the input length is less than or equal to max_input_length.
2. Run local scrubbing or redaction when available.
3. Block prompt-injection patterns if injection_block is enabled.
4. Decide whether detected secrets should block or only alert.
5. Create or update the trace with the final policy decision.

Example local policy decision:

{
  "policy_decision": {
    "allowed": false,
    "reason": "input_length_exceeded",
    "max_input_length": 10000,
    "observed_input_length": 12488
  }
}

Public clients should include policy outcomes as metadata or structured trace fields, not as raw hidden prompts.

Example allowed-but-flagged decision:

{
  "policy_decision": {
    "allowed": true,
    "reason": "secret_detected_alert_only",
    "secret_action": "alert"
  }
}

Example blocked decision emitted as trace metadata:

{
  "metadata": {
    "policy_decision": "blocked",
    "policy_reason": "secret_detected_blocked",
    "secret_action": "block"
  }
}

Routing

{
  "routing": {
    "tiers": {
      "simple": "economy-model",
      "medium": "standard-model",
      "complex": "frontier-model"
    },
    "fallbacks": ["standard-model", "economy-model"]
  }
}

Routing tiers are project-defined model identifiers. The CLI should pass model intent and trace metadata to Olyx rather than hardcoding provider-specific routing logic.

Routing Tier Semantics

Routing identifiers are project-owned names. They do not need to reveal the provider or model vendor.

Example trace metadata for routing:

{
  "metadata": {
    "routing_tier": "medium",
    "feature": "support-response",
    "environment": "production"
  }
}

Clients should not override routing to a provider-specific model unless the project policy explicitly allows it.

Example local interpretation:

{
  "metadata": {
    "routing_tier": "complex",
    "feature": "claims-escalation",
    "policy_decision": "allowed"
  }
}

Telemetry

{
  "telemetry": {
    "mode": "anonymized",
    "allowed_fields": [
      "trace_id",
      "created_at",
      "latency_ms",
      "token_count",
      "cost",
      "status",
      "policy_decision"
    ]
  }
}

Public telemetry may include normal trace payloads. Anonymized telemetry and customer-managed telemetry should avoid raw prompts, completions, user identifiers, and tool payload bodies.

Allowed Field Semantics

When telemetry.mode is anonymized, avoid customer identifiers and payload bodies even if they appear in local application logs.

Recommended anonymized substitutions:

Example Policy

{
  "version": "2026-05-27",
  "project_id": 123,
  "distribution": {
    "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
  },
  "guardrails": {
    "max_input_length": 10000,
    "pii_threshold": 0.7,
    "injection_block": true,
    "secret_action": "alert"
  },
  "routing": {
    "tiers": {
      "simple": "economy-model",
      "medium": "standard-model",
      "complex": "frontier-model"
    },
    "fallbacks": ["standard-model", "economy-model"]
  }
}

Validation Checklist

Before using a policy snapshot, a client should validate:

Client Validation Example

See the Quick Start guide for the assertSupportedPolicy guard function and integration walkthrough. The checklist above maps directly to the checks that function performs.

Minimal Type Shape

type OlyxPolicy = {
  version: string;
  project_id: number;
  distribution: {
    distribution_channel: 'cli' | 'agent';
    telemetry_mode: 'public' | 'anonymized' | 'customer_managed';
    payload_storage_mode: 'cloud_full' | 'cloud_anonymized' | 'customer_managed';
    payload_retained: boolean;
    replay_execution_mode: 'cloud' | 'disabled' | 'agent_local';
    secrets_boundary: 'customer_environment';
    cloud_payloads: boolean;
    local_ref_required: boolean;
  };
  runtime_failover?: {
    preferred_runtime: 'cloud' | 'edge';
    fallback_order: string[];
    data_boundary: 'olyx_cloud' | 'customer_environment';
    fail_closed: boolean;
    cloud_fallback: {
      enabled: boolean;
      mode: 'cloud-primary' | 'redacted-envelope' | 'redacted-summary-only';
      requires_redaction: boolean;
      raw_payloads_allowed: boolean;
      provider_secrets_allowed: false;
    };
    edge_fallback: {
      enabled: boolean;
      targets: string[];
      fail_closed: boolean;
    };
  };
  guardrails?: {
    max_input_length?: number;
    pii_threshold?: number;
    injection_block?: boolean;
    secret_action?: 'alert' | 'block' | 'redact';
  };
  routing?: {
    tiers?: Record<string, string>;
    fallbacks?: string[];
  };
  telemetry?: {
    mode: 'public' | 'anonymized' | 'customer_managed';
    allowed_fields?: string[];
  };
};

What To Read Next

• Quick Start — assertSupportedPolicy guard and first-trace walkthrough.
• Protocol — how a client fetches and caches config at startup.
• Privacy And Security — how telemetry mode and payload boundaries affect data handling.
• Routing — how routing tier fields in policy translate to model selection.