Quickstart
This quickstart uses the CLI so every step is copyable. Run it from a directory linked to your Alien project.
1. Enable AI Gateway
Choose one model to test:
alien projects capabilities enable ai \
--model byo/claude-opus-5Create an API key for requests from your backend:
alien api-keys create \
--for ai-gateway \
--description local-quickstartThe secret is shown once. Save it as ALIEN_AI_API_KEY.
export ALIEN_AI_API_KEY="..."2. Connect your test account
Create a setup link for a customer your application calls org_123:
alien onboard "Test customer" \
--external-id org_123 \
--setup-items modelsOpen the returned link and connect a provider account you control. Use the same customer ID in every request for this connection:
export CUSTOMER_ID="org_123"3. Send a request
The CLI can print a request for the active Alien environment:
alien examples ai-gateway \
--protocol openai-chat \
--model byo/claude-opus-5Run the printed command. It is equivalent to:
curl "https://ai.alien.dev/v1/chat/completions" \
-H "Authorization: Bearer $ALIEN_AI_API_KEY" \
-H "X-Alien-External-ID: $CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "byo/claude-opus-5",
"messages": [{"role": "user", "content": "Say hello in five words."}]
}'Use the model ID returned by your project if it differs from this example.
4. Put it in your backend
import OpenAI from "openai"
const ai = new OpenAI({
baseURL: "https://ai.alien.dev/v1",
apiKey: process.env.ALIEN_AI_API_KEY,
defaultHeaders: {
"X-Alien-External-ID": customer.id,
},
})
const response = await ai.chat.completions.create({
model: "byo/claude-opus-5",
messages: [{ role: "user", content: "Hello" }],
})Resolve customer.id from the authenticated server-side account. Do not accept it directly from browser input.
If the request fails
Search AI Gateway diagnostics without exposing prompts or responses:
alien logs --source ai-gateway --since 1hFilter by model, provider, or outcome:
alien logs --source ai-gateway \
--status provider-error \
--model byo/claude-opus-5