Skip to main content
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