# experiential (experientiallabs/experiential)

> Experiential is an open source gateway and router for agent workflows that lets you use hosted, BYOK, and local models through one OpenAI-compatible API, control who can spend how much on which models, and turn production traffic into a custom optimized router or your own fine-tuned model.

- GitHub: https://github.com/experientiallabs/experiential
- GitHub.Locker page: https://github.locker/experientiallabs/experiential
- Stars: 17.6K
- Language: Python
- License: Apache-2.0
- Last push: 2026-11-18

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is this a gateway I run myself, or only a hosted service?**

Both: you can run a local OpenAI-compatible gateway yourself via the exp CLI, or use the managed hosted platform at platform.experientiallabs.ai which serves the same API without any local setup.

**How do I get the gateway running?**

Run exp (or exp run) to start the local gateway; the first-run setup wizard walks you through provider, model, and reasoning-effort selection, sets a default $50.00 command budget, and prints a one-time API key you then use to send requests.

**Do I need my own provider API keys to use it?**

For BYOK mode you connect your own OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks, or OpenRouter keys for free pass-through; it also supports hosted and local models if you don't want to bring your own keys.

**Which coding agents can I point at the gateway?**

The setup docs cover repointing Claude Code, Cursor, Codex, Aider, and similar coding agents (plus Conductor) at the gateway's OpenAI/Anthropic-compatible endpoint.

**Does it track my prompts or data?**

Anonymous aggregate PostHog telemetry is enabled by default but explicitly excludes prompts, traces, actions, observations, paths, model names, credentials, and raw customer content; the opt-in preference is stored locally.

**How does it optimize costs from my traffic?**

It ingests OpenTelemetry traces from your agent traffic, walks you through a build wizard for providers, models, and budget, and can then fine-tune an open source model you own using Tinker based on those traces.

**What is Tinker used for here?**

After collecting traces from your router, Experiential uses Tinker to fine-tune an open source model that you own and control, rather than depending on a vendor's closed model.

**Can I try the optimization workflow without my own traffic first?**

Yes, there's a public terminal-tasks OTLP dataset you can download to test the trace-based optimization flow before uploading your own data.

**Does it support Anthropic's API format, or just OpenAI's?**

The gateway serves both an OpenAI-compatible API and an Anthropic Messages-compatible API from the same endpoint.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/experientiallabs/experiential/blob/main/README.md

# Experiential

[![gateway latency](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fexperientiallabs%2Fexperiential%2Fbadges%2Fgateway-latency.json)](https://github.com/experientiallabs/experiential/actions/workflows/gateway-latency.yml?query=branch%3Amain)

Experiential is an open source gateway and router for agent workflows:

1. Use hosted, BYOK, and local models through one OpenAI-compatible API.
2. Control which users and agents can use which models, for which use cases, and how much they can spend.
3. Turn production traffic into a custom router or model optimized for quality, speed, and cost.

![Experiential workspace usage dashboard showing model traffic, identities, and spend](https://raw.githubusercontent.com/experientiallabs/experiential/main/assets/experiential-workflow.png)

<p align="center">
  🌐 <a href="https://platform.experientiallabs.ai">Platform</a> |
  📚 <a href="https://platform.experientiallabs.ai/docs">Docs</a> |
  <a href="https://discord.gg/B6sM8xTVwU"><img src="https://cdn.simpleicons.org/discord/5865F2" alt="" width="16" height="16"> Discord</a>
</p>

## Getting Started

Start a local OpenAI-compatible gateway. On first run, the setup wizard uses the shared provider,
model, and reasoning-effort selectors, persists every selected provider connection, then shows
defaults for the public alias, identity, and `$50.00` command budget before printing a one-time key:

```bash
pip install experiential
exp
```

Choose a public alias such as `opus-5`, capture the issued key, and send a request:

```bash
export EXP_GATEWAY_KEY=...
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $EXP_GATEWAY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"opus-5","messages":[{"role":"user","content":"Help me"}]}'
```

## Setup / get started with the hosted gateway

Prefer a managed gateway to running one locally? The hosted platform at
[platform.experientiallabs.ai](https://platform.experientiallabs.ai) serves the same
OpenAI-compatible (and Anthropic Messages) API at `https://api.experientiallabs.ai/v1`.
See [SETUP.md](./SETUP.md) for copy-paste prompts you hand to your coding agent
(Claude Code, Cursor, Codex, and similar); the agent runs the setup for you. It
collects four prompts:

- Upload your LLM traces as telemetry: create an account instantly from your email, then pull or upload your existing LLM traces onto the platform as telemetry.
- Connect your inference provider keys (BYOK): create an account, then connect your own OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks, or OpenRouter keys for free pass-through.
- Start calling models on the gateway: make your first `/v1` call with the OpenAI and Anthropic SDKs using an `xpl_` key, and optionally repoint your existing coding agents.
- Full onboarding: create an account instantly from your email, connect your keys, import your spend, then repoint every coding agent (Claude Code, Cursor, Codex, Aider, and similar) or Conductor at the gateway.

## Using the API

Start the local gateway with `exp` (or `exp run`); the compiled native data plane
serves every route on loopback. From Python, load a fitted project router as an
official OpenAI client backed by its own private gateway:

```python
import exp

with exp.load_router("my-project") as client:
    response = client.chat.completions.create(
        model="my-project",
        messages=[{"role": "user", "content": "hello"}],
    )
```

## Coding Agent

`exp code` runs [exp-code](./agent/README.md), Experiential's open-source coding and cowork
agent built on [Pi](https://github.com/earendil-works/pi). It needs Node.js 22.19 or newer and
uses your running local gateway, or the hosted gateway after `exp login`:

```bash
exp code                       # interactive terminal UI
exp code -p "Summarize sales.csv into report.docx"
```

Every argument goes to exp-code, so its print, JSON, and RPC modes work through `exp code` too.

## Capture Traffic

Capture is designed to collect supported traces from the Codex and Claude Code desktop apps using
your existing ChatGPT or Claude subscription, while requests go directly to OpenAI or Anthropic.
It requires macOS, Python 3.13 or newer, and approval for its extension and certificate:

```bash
exp capture
```

Capture is experimental; macOS network reliability is still under investigation.

Use Experiential's gateway as middleware to control costs, enforce guardrails, and optimize quality,
costs, and speed. Leave the terminal open while you work. Press Ctrl+C to stop capture.
View your [capture telemetry](https://platform.experientiallabs.ai/api-keys?section=capture).

## Optimize from Traffic

First, collect OpenTelemetry traces from your current agent. If you just want to try it out, grab
the public [terminal-tasks OTLP dataset](https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces):

```bash
curl -L -o traces.otel.jsonl \
  https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonl
```

Then build a project. The build command walks you through providers,
models, and budget, and asks for your trace file:

```bash
# Build simulation from your agent traces and optimize a router against it
exp build support-agent
```

After collecting traces from your router, fine-tune an open source model you own using
[Tinker](https://tinker.thinkingmachines.ai/).

```bash
exp optimize model support-agent
```

## Telemetry

Anonymous aggregate PostHog product telemetry is enabled by default. It never includes prompts,
traces, actions, observations, paths, model names, credentials, or raw customer content.

```bash
exp config telemetry status
exp config telemetry disable
exp config telemetry enable
```

The preference is stored locally in `.exp/settings.toml`.

## Development

```bash
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -q
```

Repository and documentation conventions live in [AGENTS.md](./AGENTS.md).

