> ## Documentation Index
> Fetch the complete documentation index at: https://infercrane.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Governed external capacity

> Explicit, budgeted health or queue overflow to an OpenAI-compatible external target.

# Governed external capacity

InferCrane can route to a registered external API when all primary targets are unhealthy or an
explicit bounded queue policy is satisfied. This
is emergency capacity, not a model marketplace: InferCrane does not resell access, select a model,
or hide the external provider from the operator.

<Warning>
  External fallback can transmit prompts and generated output outside infrastructure you control and
  can create a separate provider charge. Enabling it requires an explicit privacy acknowledgement and
  hard request and cost-reservation limits.
</Warning>

External capacity has two explicit scopes:

* **Stable endpoint binding:** an authenticated external API participates in an immutable `manual`,
  `primary-fallback`, or `weighted` serving plan. This is the preferred one-endpoint composition.
* **Deployment overflow:** emergency external capacity is selected when one concrete deployment's
  primary targets are unhealthy or its bounded queue policy is satisfied.

Both scopes use reference-only credentials, consent, in-memory budget leases, and no request replay.
They are configured separately so a deployment policy cannot silently change an endpoint plan.

See [Stable endpoints](/features/endpoints#add-an-authenticated-managed-api) for first-class endpoint
bindings.

## Configure OpenRouter fallback

Inject the credential into the control-plane environment, then register only its reference:

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
export OPENROUTER_API_KEY='...'
infercrane secret create openrouter --from-env OPENROUTER_API_KEY --output json
```

Register the exact endpoint and model mapping. Replace `SECRET_REFERENCE_ID` with the returned ID:

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
infercrane target add openrouter-qwen \
  --provider openrouter \
  --url https://openrouter.ai/api/v1 \
  --upstream-model qwen/qwen3-8b

infercrane external configure qwen-prod \
  --target openrouter-qwen \
  --adapter openrouter \
  --secret-reference SECRET_REFERENCE_ID \
  --request-limit 100 \
  --cost-limit-usd 10.00 \
  --max-request-cost-usd 0.10 \
  --acknowledge-external-data \
  --enable
```

The policy attaches the registered fallback target to `qwen-prod`; it is excluded from ordinary
healthy-primary routing. Inspect the durable policy and reserved budget:

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
infercrane external inspect qwen-prod
infercrane external inspect qwen-prod --output json
```

For queue overflow, opt in to hysteresis and cooldown explicitly:

```bash theme={"theme":{"light":"github-light-default","dark":"vesper"}}
infercrane external configure qwen-prod \
  --target openrouter-qwen \
  --adapter openrouter \
  --secret-reference SECRET_REFERENCE_ID \
  --mode health_and_queue \
  --queue-threshold 4 \
  --breach-intervals 3 \
  --recovery-intervals 3 \
  --cooldown-seconds 60 \
  --signal-max-age-seconds 30 \
  --request-limit 100 \
  --cost-limit-usd 10.00 \
  --max-request-cost-usd 0.10 \
  --acknowledge-external-data \
  --enable
```

Missing or stale queue metrics never imply an empty queue. Consecutive observations and cooldown
prevent route oscillation. Every selection, recovery, denial, reason change, and hysteresis-counter
transition is persisted with the exact policy and signal snapshot. Identical steady-state holds are
coalesced rather than writing an unbounded row on every health interval.

## Selection and budget behavior

The reconciler publishes one external route after every ordinary target is unhealthy or after the
configured queue breach persists for the required intervals. Before
each external transmission, the gateway atomically consumes a request reservation and the configured
worst-case cost reservation. Exhaustion returns an error before sending bytes.

Reservations are deliberately conservative. A request that reserves more than its eventual provider
charge does not receive an automatic refund because InferCrane does not ingest an authoritative
provider invoice. `cost_limit_usd` is therefore an authorization ceiling, not an estimated bill.

InferCrane selects the provider before transmission. It never replays a request after a possible send,
never duplicates streaming traffic, and does not silently shadow user requests. Selection, denial,
budget counters, and health changes remain available through persisted events and request records.

## Disable fallback

Re-run `external configure` without `--enable` using the same target, reference, acknowledgement, and
limits. This replaces the policy with a disabled policy; it does not delete the target or secret
reference.

## Current limits

* Weighted, semantic, shadow, and request-duplicating external routing are not implemented.
* Environment references are currently the only secret resolver.
* Provider prices are not fetched or fabricated.
* Real OpenRouter billing qualification is deferred to the consolidated manual release gate.