> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/ai-gateway/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# AI Gateway

## Docs

- [Supported models](https://docs.astropods.com/ai-gateway/models.md): Model ids the AI Gateway accepts, and what each one is for
- [Chat completions](https://docs.astropods.com/ai-gateway/chat.md): Call the gateway from any OpenAI-compatible client, with streaming and structured output
- [Embeddings](https://docs.astropods.com/ai-gateway/embeddings.md): Turn text into vectors for RAG and semantic search
- [Decisions](https://docs.astropods.com/ai-gateway/decisions.md): Ask a decision model typed questions about a state and get structured answers
- [Vision](https://docs.astropods.com/ai-gateway/vision.md): Send images alongside text to a vision-capable model
- [Web search](https://docs.astropods.com/ai-gateway/web-search.md): Let a GPT model ground its answers in current search results
- [Anthropic API](https://docs.astropods.com/ai-gateway/anthropic.md): Run Claude Code and the Claude Agent SDK against the gateway's native Messages passthrough
- [Errors and limits](https://docs.astropods.com/ai-gateway/limits.md): Status codes the gateway returns, and the capabilities it doesn't offer


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/ai-gateway/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# AI Gateway

Set one line in your spec and your agent gets a managed API key for calling supported models. The gateway is OpenAI-API-compatible, so it works with the SDKs and frameworks you already use.

## Quick start

Scaffold a new agent wired to the gateway in one step:

```bash
ast create my-agent --model gateway
```

This generates a gateway model in the spec and agent code that reads the injected env vars, with no provider key to configure. To enable the gateway on an existing agent, declare a model with `provider: gateway` in `astropods.yml` and list the models you want to choose between:

```yaml
models:
  default:
    provider: gateway
    models: [claude-sonnet-4-6, claude-haiku-4-5]
```

The `models` list is a menu of **options**. At deploy time, in the web console and CLI, you pick one, and it is injected as `MODEL_<NAME>` (here `MODEL_DEFAULT`). Your agent code reads the model id from that env var.

> **Note**
>
> The `agent.astro_ai_gateway: true` boolean is **deprecated** in favor of a `provider: gateway` model. It still works (it enables the gateway with no deploy-time model selection), but declaring a gateway model is preferred and lets you pick the model at deploy.

## Injected environment variables

On `ast deploy` (and `ast project`), your agent container receives:

| Env var                 | Purpose                                                                           |
| ----------------------- | --------------------------------------------------------------------------------- |
| `ASTRO_GATEWAY_URL`     | Gateway host (stable). Append `/v1` for the OpenAI-compatible API.                |
| `ASTRO_GATEWAY_API_KEY` | Bearer credential (stable). Treat as a secret.                                    |
| `MODEL_<NAME>`          | The model chosen at deploy for the gateway entry `<name>` (e.g. `MODEL_DEFAULT`). |

## Local development

`ast project` handles the gateway automatically. Run:

```bash
ast login
ast project
```

Your local agent container receives the same `ASTRO_GATEWAY_*` env vars it would have in production. Code written against those env vars works identically in dev and prod.

> **Note**
>
> Run `ast login` first if you haven't. The gateway is account-scoped, so the CLI needs to know who you are.

## Mixing with your own keys

`astro_ai_gateway: true` is independent of any `models` you declare. You can use the gateway for some calls and your own provider key for others:

```yaml
agent:
  image: my-agent:latest
  astro_ai_gateway: true        # gateway-managed models
models:
  custom-fine-tune:
    provider: openai      # your own OpenAI key for a specific use case
```

Your agent code reads `ASTRO_GATEWAY_API_KEY` for gateway calls and `OPENAI_API_KEY` for the bring-your-own-key (BYOK) provider.

## Next steps

#### [Chat completions](/ai-gateway/chat)

Point an OpenAI-compatible client at the gateway.

#### [Supported models](/ai-gateway/models)

Every model id the gateway accepts.

#### [Decisions](/ai-gateway/decisions)

Get typed answers from a decision model.

#### [Anthropic API](/ai-gateway/anthropic)

Run Claude Code and the Claude Agent SDK on the gateway.

#### [Errors and limits](/ai-gateway/limits)

Status codes, rate limits, and what the gateway doesn't cover.