# Your first deployment

> The minimal path: one catalog model, one provider, verified and tested.

URL: https://boelabs.com/en/docs/ai-gateway/first-deployment
Language: English

Connect a provider to an existing gateway and check the resolved configuration before saving it.
For local installation, follow [Quickstart](https://boelabs.com/docs/ai-gateway/quickstart).

## Before you start

You need a running gateway, its master key, and a provider API key. Set the gateway address:

```bash
export GATEWAY=http://localhost:4000
export MASTER_KEY=replace-with-your-master-key
```

<Steps>
<Step>

## Pick a catalog model

Known models need no `catalogEntry` — their capabilities, limits, and pricing already live in the
adapter's catalog. Browse `src/adapters/<provider>/catalog.json` in the repo, and choose a model included in that catalog (e.g. `gpt-5.5` for OpenAI).

</Step>
<Step>

## Dry-run it

`POST /admin/deployments/resolve` validates and resolves the exact same body a real
`POST /admin/deployments` would use, **without saving anything or touching credentials encryption** —
use it to check the request configuration. It does not contact the provider or verify the API key:

```bash
curl -X POST "$GATEWAY/admin/deployments/resolve" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModel": "general",
    "adapterKey": "openai",
    "upstreamModel": "gpt-5.5",
    "credentials": { "apiKey": "sk-..." }
  }'
```

The response shows `source: "catalog"` (confirming it recognized the model — no `catalogEntry` needed),
plus the resolved operations and transports. If `source` comes back `"custom"` instead, the model isn't
in the catalog and you'll need to follow the custom-model path in
[Creating deployments](https://boelabs.com/docs/ai-gateway/creating-deployments#custom-models-openai-compatible) instead.

</Step>
<Step>

## Save the deployment

Send the validated body to the create endpoint:

```bash
curl -X POST "$GATEWAY/admin/deployments" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModel": "general",
    "adapterKey": "openai",
    "upstreamModel": "gpt-5.5",
    "credentials": { "apiKey": "sk-..." }
  }'
```

</Step>
<Step>

## Test the connection

Create a [virtual key](https://boelabs.com/docs/ai-gateway/virtual-keys) allowed to call `general`, then set `API_KEY` to its returned secret. This request verifies both the gateway configuration and the upstream connection:

```bash
curl -X POST "$GATEWAY/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "general", "messages": [{ "role": "user", "content": "Say hi" }] }'
```

Confirm that the response contains an assistant message. A successful resolve alone does not
prove that the provider credentials or model access work.

</Step>
</Steps>

## Next steps

- [Creating deployments](https://boelabs.com/docs/ai-gateway/creating-deployments) — every provider, custom models, images/embeddings/audio.
- [Routing](https://boelabs.com/docs/ai-gateway/routing) — what happens once `general` has more than one deployment.
- [Virtual keys](https://boelabs.com/docs/ai-gateway/virtual-keys) — scoped, rate-limited client keys instead of the master key.