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

# How Astrolabe Cloud Works

> Hosted request lifecycle, stack resolution, billing, fallback, and traceability.

Astrolabe Cloud sits between your application and upstream model providers. Your app talks to one OpenAI-compatible gateway, and Astrolabe handles key validation, balance reservation, stack policy, provider execution, usage billing, and observability.

## System map

Astrolabe Cloud has four production surfaces:

1. **Cloud app** at `https://app.astrolabe.run` for workspace setup, API keys, billing, routing stacks, usage, and traces.
2. **Gateway** at `https://api.astrolabe.run/v1` for model requests.
3. **Control plane** for workspace state, API key mirrors, billing ledger, stack versions, and trace records.
4. **Provider layer** through OpenRouter for concrete model execution.

## Request lifecycle

For `POST /v1/responses` and `POST /v1/chat/completions`:

1. The gateway extracts the API key from `Authorization: Bearer ...` or `x-api-key`.
2. The key is resolved to a workspace and key prefix.
3. Rate limits are checked for the key.
4. Astrolabe estimates request size and reserves prepaid workspace balance.
5. The requested model is normalized. Virtual aliases such as `auto` resolve to `astrolabe/auto`.
6. The gateway resolves the active routing stack.
7. The stack applies boundaries, objectives, fallback policy, verification settings, and request overrides.
8. Astrolabe selects a concrete serving model and calls OpenRouter.
9. Fallback, verification, schema recovery, or policy blocking may run depending on the stack and response.
10. Usage is finalized from provider usage where available.
11. Billing, model-call records, and route traces are written back to the control plane.
12. The response returns with Cloud, stack, model, policy, rate-limit, and request-id headers.

## Stack resolution

Astrolabe chooses a stack in this order:

1. `metadata.astrolabe.stack` on the request.
2. Stack assigned to the API key.
3. Stack assigned to the workspace.
4. Managed default stack.

If a requested stack slug does not exist or is not active for the workspace, the gateway returns a stack resolution error before provider execution.

## Billing model

Astrolabe Cloud uses prepaid credits.

* A request must pass auth, workspace status, and balance checks before provider work starts.
* Astrolabe reserves enough balance for the selected route.
* Successful provider usage becomes the customer debit.
* Failed, rejected, duplicate, unpriced, or missing-usage requests are recorded as unbillable.
* Route traces and usage rows remain available for debugging.

## What clients can observe

Log `x-astrolabe-cloud-request-id` for every request. It is the primary support and trace lookup key.

Response headers can expose:

* workspace and key prefix
* rate-limit state
* selected model and provider
* stack id, name, and version
* policy status and decision kind
* category, action class, complexity, and lane
* verification status and confidence
* estimated baseline cost and estimated savings

## Deep references

* [Routing Stack Concepts](/routing-stacks/concepts)
* [Request Stack Selection](/routing-stacks/request-selection)
* [Routing Reference](/routing-reference)
* [API Reference](/api-reference/introduction)