llama-dash

Routing rules are an ordered list in the proxy transform pipeline. The first enabled rule that matches a request decides what happens next. Requests that match no rule go to llama-swap and require a llama-dash API key.

continue: pass through unchanged
rewrite_model: map the requested model to another
reject: block the request
set a per-rule auth mode: require_key or passthrough
target a configured direct HTTPS upstream, bypassing llama-swap for that request while keeping proxy logging

Direct targets can reference encrypted upstream credentials. Passthrough rules can preserve the client Authorization header for upstream OAuth or API-key validation. This is how Claude Code passthrough, OpenCode & ChatGPT passthrough, and Codex & ChatGPT passthrough work.

Policies

Start simple

You do not need routing rules to send local requests through llama-swap. Add a rule when a request needs a different destination, model name, or authentication mode. Put narrow rules above broad rules, because only the first match applies.

If you want to...	Use
Send local requests to llama-swap	No rule. The default applies.
Translate a public model name	`rewrite_model`, or an alias when the mapping should apply everywhere.
Forward Claude Code, OpenCode, or Codex OAuth	`continue` with `passthrough` auth and preserved `Authorization`.
Use a stored provider secret	A direct target or relay with a credential binding. The caller still needs a valid llama-dash API key.

Evaluation order

Rules are stored with an explicit order. The first enabled rule whose matchers all pass wins.

Match fields:

Endpoint, such as /v1/chat/completions or /v1/messages.
Requested model from the request body.
API key ID.
Stream mode: any, stream, or non-stream.
Minimum estimated prompt tokens.
Maximum estimated prompt tokens.

Prompt-token bounds use llama-dash's local estimate from the incoming JSON body. They are useful for coarse routing and rejection, not billing-grade token accounting.

Actions

continue records the match and leaves the model unchanged.
rewrite_model changes the request body's model before alias resolution and forwarding.
reject returns 422 with routing_rule_rejected and the configured reason.

API-key model allow-lists are checked before routing and again after a rewrite. This prevents a key from requesting an allowed alias that rewrites into a disallowed target.

Targets

The default target is llama-swap. A rule can also target a direct HTTPS upstream while keeping llama-dash logging, metrics, attribution, and request detail.

Direct upstream URLs must:

Use https:.
Contain no username, password, query, or hash.
End with /v1, except for the ChatGPT Codex target https://chatgpt.com/backend-api/codex.
Use an allowed host. The current allow-list is api.openai.com, api.anthropic.com, and chatgpt.com.

Auth modes

require_key means llama-dash authenticates with one of its API keys.
passthrough means the matched request can skip llama-dash API-key auth. If preserveAuthorization is enabled, the upstream can validate the client-supplied credential.

Direct passthrough rules must have at least one matcher. This prevents a broad direct passthrough catch-all rule from forwarding every request to an external upstream without a condition.

When preserveAuthorization is enabled on a passthrough rule, llama-dash forwards the inbound Authorization header instead of stripping it before upstream forwarding.

Credential bindings

Rules can attach stored upstream credentials in two ways:

Replace a placeholder such as {{llama-dash:credential:<slug>}} in a header template.
Set a header directly from a stored credential.

Credential-bearing rules still require a valid llama-dash API key first. See Upstream credentials.