relaylet

Real clients · scripted provider · not yet live

CH1client CH2relaylet CH3provider

Your agent counted two. The provider got three.

relaylet sits on the wire between your coding agent and the model provider. It forwards every byte unchanged and journals every attempt: what was sent, what it may cost, and what is still unknown.

Keep the client you already use: Codex (OpenAI Responses) or Claude Code (Anthropic Messages).

Codex
8/8 scenarios
Claude Code
8/8 scenarios
Test suite
380 test cases

Capture · cut stream

codex-cli 0.160.0 → relaylet → scripted provider · session 7edd932c902c

Codex's own counter23,240tokens used, as printed

May be billed3upstream requests

Usage reported2by the provider

Usage unknown1never shown as zero

relaylet's journal for this capture

  1. #1reported#1 completed. Usage reported by the provider.
  2. #2unknown#2 the upstream stream ended abruptly after 1530 bytes without a terminal event. The provider may still have processed and billed it; relaylet passed the failure through and did not retry.
  3. #3reported#3 completed. It repeats attempt #2 (same request content: a client retry).

A real client against relaylet's deterministic stand-in provider; no real model was involved. The agent's counter covers the requests that completed. Attempt #2 may still have been billed.

Who relaylet is for

Three promises, measured on the wire

CH2Byte-faithful

Nothing rewritten.

The client's request and the provider's stream pass through unchanged, including the opaque reasoning state that tool loops depend on. No model is silently substituted, and nothing is retried behind your back.

Request and response bytes were identical on both sides in every relayed scenario, for both clients.

RECHonest accounting

Every attempt closes one of three ways.

  • Settled Charged from the usage the provider reported.
  • Not charged Blocked before it left. Nothing was sent.
  • Unresolved Sent, outcome unknown. It keeps its hold until reconciled.

Unknown, then known. Reconciled against the provider's own usage export, a cut OpenAI attempt became resolved_actual: the export's request count makes the match a proof. Anthropic's export counts no requests, so the same match is an estimate the operator must accept (resolved_estimate). Tested end to end against the stand-in provider; not yet on a real export.

CH1Hard limits

Stops before it spends.

Credit for a request's worst case is held before the request leaves. Each key, one per person or agent, can carry its own daily, monthly or lifetime cap; a request that could break it is refused unsent. Keys are scoped, rate-limited and revocable.

When a Codex session's request limit ran out, Codex kept retrying: 6 attempts were blocked and none reached the provider. A key's cap counts an unknown outcome at its worst case until it is reconciled; 32/32 deliberately injected faults in the cap logic were caught by its tests. Refused at the cap, real Claude Code stopped after 1 request; real Codex retried until 6, all refused locally, and both printed the reason. Requests that reached the provider: 0.

Connection passport

Two real clients. Eight ways to fail. Every guarantee held.

Each client ran a two-turn tool job through relaylet, then the same job under a cut stream, a rate limit, a spent budget, the wrong model, the wrong key and a cancel. Pick a scenario to see the trace, relaylet's own journal lines, and what the client did.

Evidence level

  1. Documented
  2. Fixture tested
  3. Real client, scripted provider
  4. Live observed
  5. Customer accepted

Codex · codex-cli 0.160.0

Direct baseline

The client talks to the scripted provider directly. No relay; the reference run.

3/3 guarantees held

Journal

no relay in the path (baseline)
upstream requests 2 · tool turns A 1 · B 1

Guarantees

  • Workspace unchanged by the job passed
  • Job done: every planted issue found, with a fix passed
  • Tool call and opaque reasoning state returned intact passed

Client behaviour

  • Opaque reasoning state: intact
  • Client exit code 0 · 2.17 s

Codex · codex-cli 0.160.0

Relayed

The same two-turn tool job, through relaylet.

6/6 guarantees held

Journal

attempts 2 | forwarded 2 | blocked locally 0 | client retries 0
upstream requests that may be billed: 2 (usage reported 2, unknown 0)
reported tokens: input 22834 | output 394 | total 23228 | cost unpriced

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Job done: every planted issue found, with a fix passed
  • Tool call and opaque reasoning state returned intact passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed

Client behaviour

  • Opaque reasoning state: intact
  • Client exit code 0 · 1.91 s

Codex · codex-cli 0.160.0

Cut stream

The provider cuts its stream mid-response, once.

6/6 guarantees held

Journal

attempts 3 | forwarded 3 | blocked locally 0 | client retries 1
upstream requests that may be billed: 3 (usage reported 2, unknown 1)
reported tokens: input 22846 | output 394 | total 23240 | cost unpriced
- #2 the upstream stream ended abruptly after 1530 bytes without a terminal event. The provider may still have processed and billed it; relaylet passed the failure through and did not retry.
- #3 completed. It repeats attempt #2 (same request content: a client retry).

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Cut stream recorded as aborted, outcome unknown passed
  • Tool call and opaque reasoning state returned intact passed

Client behaviour

  • Retried the cut request on its own
  • Recovered and finished
  • Client exit code 0 · 1.52 s

Codex · codex-cli 0.160.0

Rate limit

The provider answers HTTP 429, once.

6/6 guarantees held

Journal

attempts 1 | forwarded 1 | blocked locally 0 | client retries 0
upstream requests that may be billed: 1 (usage reported 0, unknown 1)
reported tokens: none | cost unpriced
- #1 upstream answered HTTP 429 (rate_limit_exceeded); relaylet forwarded it unchanged and did not retry.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Upstream error recorded and passed through unchanged passed
  • relaylet sent each request upstream at most once passed

Client behaviour

  • Did not recover; exited
  • Did not retry after the 429
  • Client exit code 1 · 0.72 s

Codex · codex-cli 0.160.0

Request budget

The session's upstream request limit runs out mid-job.

6/6 guarantees held

Journal

attempts 7 | forwarded 1 | blocked locally 6 | client retries 5
upstream requests that may be billed: 1 (usage reported 1, unknown 0)
reported tokens: input 11165 | output 99 | total 11264 | cost unpriced
- #2 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream.
- #3 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream. It repeats attempt #2 (same request content: a client retry).
- #4 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream. It repeats attempt #2 (same request content: a client retry).
- #5 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream. It repeats attempt #2 (same request content: a client retry).
- #6 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream. It repeats attempt #2 (same request content: a client retry).
- #7 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream. It repeats attempt #2 (same request content: a client retry).

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Upstream dispatches stopped at the session limit passed
  • Blocked requests recorded as never sent passed

Client behaviour

  • 6 attempts blocked, including the client's own retries
  • Client exit code 1 · 7.62 s

Codex · codex-cli 0.160.0

Wrong model

The client asks for a model this connection does not serve.

3/3 guarantees held

Journal

attempts 1 | forwarded 0 | blocked locally 1 | client retries 0
upstream requests that may be billed: 0 (usage reported 0, unknown 0)
reported tokens: none | cost unpriced
- #1 blocked before dispatch: the client asked for model 'some-other-model', which this connection does not serve. Nothing was sent upstream.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Rejected request never reached the upstream passed

Client behaviour

  • 1 attempts rejected locally, including retries
  • Client exit code 1 · 0.80 s

Codex · codex-cli 0.160.0

Wrong key

The client presents a key relaylet does not accept.

3/3 guarantees held

Journal

attempts 6 | forwarded 0 | blocked locally 6 | client retries 0
upstream requests that may be billed: 0 (usage reported 0, unknown 0)
reported tokens: none | cost unpriced
- #1 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #2 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #3 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #4 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #5 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #6 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Rejected request never reached the upstream passed

Client behaviour

  • 6 attempts rejected locally, including retries
  • Client exit code 1 · 6.67 s

Codex · codex-cli 0.160.0

Cancel

The client is killed while the provider has not answered yet.

6/6 guarantees held

Journal

attempts 1 | forwarded 1 | blocked locally 0 | client retries 0
upstream requests that may be billed: 1 (usage reported 0, unknown 1)
reported tokens: none | cost unpriced
- #1 the client closed the connection before the provider sent anything; relaylet closed the upstream connection. Whether the provider kept working, and what it billed, is unknown.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Client cancel closed the upstream connection passed
  • Cancelled attempt recorded with unknown outcome and usage passed

Client behaviour

  • Upstream closed 1.27 s after the client left
  • Client exit code 1 · 2.78 s

Claude Code · 2.1.288

Direct baseline

The client talks to the scripted provider directly. No relay; the reference run.

3/3 guarantees held

Journal

no relay in the path (baseline)
upstream requests 2 · tool turns A 1 · B 1

Guarantees

  • Workspace unchanged by the job passed
  • Job done: every planted issue found, with a fix passed
  • Tool call and opaque reasoning state returned intact passed

Client behaviour

  • Opaque reasoning state: intact
  • Client exit code 0 · 0.61 s

Claude Code · 2.1.288

Relayed

The same two-turn tool job, through relaylet.

6/6 guarantees held

Journal

attempts 2 | forwarded 2 | blocked locally 0 | client retries 0
upstream requests that may be billed: 2 (usage reported 2, unknown 0)
reported tokens: input 37762 | output 270 | cost unpriced

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Job done: every planted issue found, with a fix passed
  • Tool call and opaque reasoning state returned intact passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed

Client behaviour

  • Opaque reasoning state: intact
  • Client exit code 0 · 0.74 s

Claude Code · 2.1.288

Cut stream

The provider cuts its stream mid-response, once.

6/6 guarantees held

Journal

attempts 3 | forwarded 3 | blocked locally 0 | client retries 1
upstream requests that may be billed: 3 (usage reported 2, unknown 1)
reported tokens: input 37770 | output 270 | cost unpriced
- #2 the upstream stream ended abruptly after 928 bytes without a terminal event. The provider may still have processed and billed it; relaylet passed the failure through and did not retry.
- #3 completed. It repeats attempt #2 (same request content: a client retry).

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Cut stream recorded as aborted, outcome unknown passed
  • Tool call and opaque reasoning state returned intact passed

Client behaviour

  • Retried the cut request on its own
  • Recovered and finished
  • Client exit code 0 · 1.25 s

Claude Code · 2.1.288

Rate limit

The provider answers HTTP 429, once.

6/6 guarantees held

Journal

attempts 3 | forwarded 3 | blocked locally 0 | client retries 1
upstream requests that may be billed: 3 (usage reported 2, unknown 1)
reported tokens: input 37767 | output 270 | cost unpriced
- #1 upstream answered HTTP 429; relaylet forwarded it unchanged and did not retry.
- #2 completed. It repeats attempt #1 (same request content: a client retry).

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Upstream error recorded and passed through unchanged passed
  • relaylet sent each request upstream at most once passed

Client behaviour

  • Recovered and finished
  • Retried after the 429
  • Client exit code 0 · 1.73 s

Claude Code · 2.1.288

Request budget

The session's upstream request limit runs out mid-job.

6/6 guarantees held

Journal

attempts 2 | forwarded 1 | blocked locally 1 | client retries 0
upstream requests that may be billed: 1 (usage reported 1, unknown 0)
reported tokens: input 18872 | output 21 | cost unpriced
- #2 blocked before dispatch: the session's upstream request limit was used up. Nothing was sent upstream.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Upstream dispatches stopped at the session limit passed
  • Blocked requests recorded as never sent passed

Client behaviour

  • 1 attempts blocked, including the client's own retries
  • Client exit code 1 · 0.55 s

Claude Code · 2.1.288

Wrong model

The client asks for a model this connection does not serve.

3/3 guarantees held

Journal

attempts 2 | forwarded 0 | blocked locally 2 | client retries 0
upstream requests that may be billed: 0 (usage reported 0, unknown 0)
reported tokens: none | cost unpriced
- #1 blocked before dispatch: the client asked for model 'some-other-model', which this connection does not serve. Nothing was sent upstream.
- #2 blocked before dispatch: the client asked for model 'some-other-model', which this connection does not serve. Nothing was sent upstream.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Rejected request never reached the upstream passed

Client behaviour

  • 2 attempts rejected locally, including retries
  • Client exit code 1 · 0.53 s

Claude Code · 2.1.288

Wrong key

The client presents a key relaylet does not accept.

3/3 guarantees held

Journal

attempts 11 | forwarded 0 | blocked locally 11 | client retries 0
upstream requests that may be billed: 0 (usage reported 0, unknown 0)
reported tokens: none | cost unpriced
- #1 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #2 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #3 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #4 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #5 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #6 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #7 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #8 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #9 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #10 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.
- #11 blocked before dispatch: the client did not present this relay's local token. Nothing was sent upstream.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Rejected request never reached the upstream passed

Client behaviour

  • 11 attempts rejected locally, including retries
  • Client exit code 1 · 170.98 s

Claude Code · 2.1.288

Cancel

The client is killed while the provider has not answered yet.

6/6 guarantees held

Journal

attempts 1 | forwarded 1 | blocked locally 0 | client retries 0
upstream requests that may be billed: 1 (usage reported 0, unknown 1)
reported tokens: none | cost unpriced
- #1 the client closed the connection before the provider sent anything; relaylet closed the upstream connection. Whether the provider kept working, and what it billed, is unknown.

Guarantees

  • No credential reached the upstream passed
  • Workspace unchanged by the job passed
  • Request and response bytes identical on both sides passed
  • Every repeated request linked to the attempt it repeats passed
  • Client cancel closed the upstream connection passed
  • Cancelled attempt recorded with unknown outcome and usage passed

Client behaviour

  • Upstream closed 1.84 s after the client left
  • Client exit code 1 · 5.39 s

What leaves your machine

Your agent sends more than your prompt. relaylet shows you what.

relaylet forwards these unchanged; it does not hide them. Measured on the model path in the relayed scenario, and outside it with every other connection refused.

Codex 0.160.0

Identifiers sent to the provider
installation_id, session_id, thread_id, turn_id, window_id
Local file paths in requests
yes
Connections outside the model path
ab.chatgpt.com, api.github.com, chatgpt.com, github.com

Claude Code 2.1.288

Identifiers sent to the provider
device_id, session_id, x-claude-code-session-id
Local file paths in requests
yes
Connections outside the model path
none observed, with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Worth knowing: Claude Code sends CLAUDE.md files from every parent directory of where it is launched. Launch it from your project, not from a folder that holds private notes.

Compared with a stock gateway

A gateway can carry the traffic. The question is what it tells you.

The same scripted provider behind LiteLLM v1.103.2, a capable open-source gateway. Its normal path carried the Codex tool loop intact. The differences are in the failures.

When this happensStock gatewayrelaylet
The client leaves while the provider is still silentNo record. The upstream request stayed open, still running at 25 s.Recorded as unknown, possibly billed. Upstream closed 2.0 s after the client left.
The provider cuts the streamThe client got HTTP 200 and a gateway-written failure; the partial events were gone.The cut is passed through as it happened, and the attempt is recorded as aborted, usage unknown.
The provider answers 429 (default settings)Retried quietly: 2 upstream requests, while the client saw a clean 200.The 429 is forwarded unchanged and never retried.
The client repeats a requestTwo unrelated rows.The second attempt is linked to the one it repeats.

Run against relaylet's scripted provider, with no real model. Setting num_retries: 0 stops the gateway's hidden retry. The experiment was run by an agent of the same product that builds relaylet, so it is not an independent review; the cancel and failure-path rows were reproduced separately.

Security

Built to be attacked.

380automated test cases

18real-browser checks on the customer console

11/11HTTPS smoke checks through the deploy kit

Status · 2026-10

What is live, and what is not.

Live

This page, served as static files.

Not yet

The hosted gateway and the customer console are not open, and no payments are taken. Reselling model access needs the providers' written permission; until then, accounts will use your own provider key.

Not established

Any real model or provider. Reconciliation against a real provider's export or invoice. Review quality (the scripted provider is deterministic code). Clients, versions or platforms not listed here.