---
title: ForgeCode with AI Gateway
product: vercel
url: /docs/ai-gateway/coding-agents/forge
canonical_url: "https://vercel.com/docs/ai-gateway/coding-agents/forge"
last_updated: 2018-10-20
type: how-to
prerequisites:
  - /docs/ai-gateway/coding-agents
  - /docs/ai-gateway
related:
  - /docs/cli/ai-gateway
  - /docs/ai-gateway/observability-and-spend/observability
  - /docs/ai-gateway/sdks-and-apis/openai-chat-completions
  - /docs/ai-gateway/observability-and-spend/budgets
summary: Connect ForgeCode to AI Gateway with the Vercel CLI or custom provider and credential files.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# ForgeCode with AI Gateway

[ForgeCode](https://forgecode.dev) is a terminal coding agent. It supports custom OpenAI-compatible providers, which you can point at AI Gateway for unified model access and spend monitoring.

## Set up with the Vercel CLI

Run the [Vercel CLI setup command](/docs/cli/ai-gateway#setup) for ForgeCode:

```bash filename="terminal"
npx vercel ai-gateway setup --agent forge
```

The command writes a gateway `[[providers]]` entry and `[session]` defaults into `~/.forge/.forge.toml`. It stores the key in the sibling `.credentials.json` with `0600` permissions, which is the only key source Forge 2.13 and later read. Re-run it to refresh the defaults.

## Configuring ForgeCode

If you can't use the Vercel CLI, configure ForgeCode manually:

- ### Create an API key
  Go to the [**AI Gateway**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway\&title=Go+to+AI+Gateway) section in the Vercel dashboard sidebar and click **API keys** to create a new API key.

- ### Add the gateway provider
  Add a `[[providers]]` entry to `~/.forge/.forge.toml`:
  ```toml filename="~/.forge/.forge.toml"
  [[providers]]
  id = "vercel-ai-gateway"
  url = "https://ai-gateway.vercel.sh/coding-agent/v1/chat/completions"
  models = "https://ai-gateway.vercel.sh/coding-agent/v1/models"
  api_key_vars = "AI_GATEWAY_API_KEY"
  response_type = "OpenAI"
  auth_methods = ["api_key"]

  [session]
  provider_id = "vercel-ai-gateway"
  model_id = "openai/gpt-6-astra"
  ```

- ### Store the key
  Forge 2.13 and later resolve keys only from `~/.forge/.credentials.json`, not the environment. Add the key to the JSON array with mode `0600`:
  ```json filename="~/.forge/.credentials.json"
  [
    {
      "provider_id": "vercel-ai-gateway",
      "auth_details": {
        "api_key": "your-ai-gateway-api-key"
      }
    }
  ]
  ```
  ```bash filename="Terminal"
  chmod 0600 ~/.forge/.credentials.json
  ```
  Older Forge releases read the key from `AI_GATEWAY_API_KEY` in the environment instead, which is why the provider also declares `api_key_vars`.

- ### Start ForgeCode
  ```bash filename="Terminal"
  forge
  ```
  Switch models in-session with `:config-model`. The picker fills from the gateway's `/models` endpoint, so the full catalog is available.

### Monitor usage and spend

View your usage, spend, and request activity in the [**AI Gateway**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway\&title=Go+to+AI+Gateway) section in the Vercel dashboard sidebar. See the [observability documentation](/docs/ai-gateway/observability-and-spend/observability) for more details.

## Environment variables

| Variable             | Description                                       |
| -------------------- | ------------------------------------------------- |
| `AI_GATEWAY_API_KEY` | Your AI Gateway API key. Used by Forge releases older than 2.13; newer releases read `.credentials.json` |

> **💡 Note:** ForgeCode calls AI Gateway through the [OpenAI-compatible Chat Completions
> API](/docs/ai-gateway/sdks-and-apis/openai-chat-completions), so any model
> that supports Chat Completions works.

## Next steps

- Browse the [models catalog](/ai-gateway/models) for available models
- Configure [spend limits](/docs/ai-gateway/observability-and-spend/budgets) on your API key


---

[View full sitemap](/docs/sitemap)