Skip to main content
skill CX Codex

logfire-gateway — Claude Code skill: setup and installation

The logfire-gateway Claude Code skill routes an application's model requests through Pydantic AI Gateway. It activates for requests to connect a Gateway key or configure a provider snippet.

MIT 232 installs ★ 156 updated 2026-10-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pydantic/skills --skill logfire-gateway -a claude-code
Open on GitHub

What logfire-gateway does

The skill configures an application's model client to send requests through Pydantic AI Gateway while keeping its current model, provider protocol, and environment conventions. It inspects the client and runnable entry point before changing the application. Coding agents themselves are outside its scope.

For Pydantic AI, the setup uses PYDANTIC_AI_GATEWAY_API_KEY and the Gateway root URL provided by Connect. Other clients keep their existing environment variable and load it into the client's API-key option. LOGFIRE_GATEWAY_API_KEY also has to be explicitly passed to that option. A Gateway key authorizes model requests; a Logfire write token sends telemetry, so the two credentials are not interchangeable.

The setup requires a Pydantic AI Gateway key and access to the selected project. Keys must stay out of source code, logs, and browser bundles. Paid provider access is activated only with the user's agreement.

What it helps with

  • route an application's model requests through Pydantic AI Gateway
  • load a Gateway key from the project's environment
  • configure the model client's Gateway URL and provider route
  • preserve the application's current model and provider protocol

Example prompts for the agent

  • Route this application's model requests through Pydantic AI Gateway.
  • Connect the existing model client to Gateway and load its key from the environment.
  • Add the Gateway provider setup for Pydantic AI while keeping the current model.

How to install logfire-gateway

1Skills CLI (Vercel)

npx skills add pydantic/skills --skill logfire-gateway -a claude-code

2Manually: put the files in place

~/.claude/skills/logfire-gateway/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/logfire-gateway/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about logfire-gateway

How do I install logfire-gateway in Claude Code?

Run npx skills add pydantic/skills --skill logfire-gateway -a claude-code. The skill file is installed at ~/.claude/skills/logfire-gateway/SKILL.md.

What does logfire-gateway do?

It configures an application's model client to send requests through Pydantic AI Gateway while preserving the existing client and provider setup. It does not configure coding agents or their telemetry.

What does logfire-gateway need to work?

It needs a Pydantic AI Gateway key and access to the chosen project. Pydantic AI setup also needs the Gateway URL from Connect; paid provider access requires the user's agreement.

Source text

SKILL.md · MIT
---
name: logfire-gateway
description: Configure an application's model calls to use the Pydantic AI Gateway. Use when the user asks to route application inference through Gateway, connect a Gateway key, or add a Gateway provider snippet. This does not configure or instrument coding agents.
---

# Configure an Application with Pydantic AI Gateway

For observing or routing Claude Code/Codex itself, use
[coding-agent setup](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/SKILL.md) instead. Keep this
application workflow separate from coding-session recording and provider setup.

Preserve the user's confirmed project, region, provider, and existing credential
mechanism. An existing application Gateway key needs no CLI login or SDK write
token. To create a key through the CLI, follow the
[CLI Gateway credential procedure](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/references/application-gateway.md).
Use the UI's Gateway Connect flow when CLI access is unavailable.

Use this skill for model traffic, provider routing, and Gateway credentials. It
is separate from `logfire-instrumentation`: a Logfire write token sends
telemetry, while a Gateway key authorizes model requests. Do not substitute one
for the other. Do not configure coding-agent providers, telemetry, or MCP integrations.

A prepared setup handoff may already identify the exact project and credentials.
Reuse it rather than repeating authentication or selecting another project.

## 1. Identify the application

Before changing files, inspect the repository and identify the existing model
client, model, provider, environment loader, and runnable entrypoint. If the
request names an application or the repository contains a clear inference
client, wire that application through Gateway. Preserve its provider protocol
and model unless the user requests a change.

If there is no inference application or the target is ambiguous, ask which
application the user wants to connect. Confirm a new application's purpose
before scaffolding it.

A Gateway setup request authorizes routing the selected application's model
calls through Gateway. Ordinary Logfire instrumentation does not imply that choice.

Continue this setup in the current agent. A prepared wizard handoff already
finished account and project selection. Do not invoke the wizard again or
launch another setup agent. Preserve the existing model client, provider
abstraction, dependency versions, and environment conventions.

## 2. Handle credentials without exposing them

Reuse an existing Gateway credential provided through the repository's secret
mechanism. Otherwise obtain a project-scoped Gateway key using the UI's Connect
flow or the [CLI credential procedure](https://pydantic.dev/.well-known/agent-skills/logfire-coding-agents/references/application-gateway.md).
Do not create a telemetry write token merely to configure an existing Gateway key.
Never print the one-time secret in a recorded terminal or agent messages.
Store it using the environment variable read by the selected SDK or Connect
snippet: `PYDANTIC_AI_GATEWAY_API_KEY` for Pydantic AI. For other clients, keep
the application's existing variable, or use `LOGFIRE_GATEWAY_API_KEY` and
explicitly read it into the client's API-key option. Setting a variable alone
does not make an arbitrary client consume it.
Keep unrelated values intact. For a local environment file, require a gitignored
regular file with user-only permissions, replace exactly one existing assignment
or insert one, and write the file atomically. Never stage or commit the
secret-bearing file or key to source control. Do not append duplicate assignments. If the existing
secret mechanism cannot be updated safely, ask the user to install the key
through their normal secret manager.

A downloaded Connect credential can use the same secret mechanism without
printing or sourcing the downloaded file. Never put a key in agent messages,
source code, logs, tests, or snapshots.

Use the environment variable expected by the selected SDK. Keep the key out of
browser code and client-side bundles. Key creation does not activate Gateway,
configure provider billing, or select a routing endpoint. If the public API
rejects creation because Gateway is inactive or permission is missing, explain
that specific prerequisite. Missing OAuth scope requires renewed consent with
the needed permission; provider activation or billing requires Gateway settings.
Do not activate paid provider access without the user's agreement. Reuse a
successfully created key; do not mint another key during a configuration retry.

## 3. Configure the detected application

Prefer the existing client and dependency versions. Make the smallest change
that preserves the application's current provider abstraction.

### Pydantic AI

Use the Gateway model form when the selected provider and model are known:

```python
from pydantic_ai import Agent

# Set PYDANTIC_AI_GATEWAY_API_KEY and PYDANTIC_AI_GATEWAY_BASE_URL from Connect.
agent = Agent('gateway/openai:gpt-5.2')
```

Set `PYDANTIC_AI_GATEWAY_BASE_URL` to the Gateway root URL supplied by Connect
for the selected region or self-hosted deployment, alongside the API key.
Use the Pydantic AI snippet's root URL, not a provider-specific endpoint copied
from another client's snippet. Preserve an explicitly configured matching URL;
do not rely on SDK region inference or a default to select the user's destination.

The normal credential is `PYDANTIC_AI_GATEWAY_API_KEY`. When the application
needs an explicit key or custom route, use the installed Pydantic AI version's
`gateway_provider()` and preserve the provider type and route from the Connect
handoff. Do not guess a provider slug from a model name.

### OpenAI-compatible clients

Use the exact Gateway base URL and route supplied by Connect, or derive the
documented regional route from the handoff and existing provider protocol. Read
the provider-specific examples in the Gateway documentation when needed. Preserve the
client's existing API shape and load its API key from the application's selected
environment variable into the client's API-key option through its normal environment
loading mechanism. Do not hard-code a regional URL when the handoff already
provides one. A self-hosted origin is not a hosted region: use its confirmed
Gateway resource and configured route, or ask for them. A documented provider
path alone does not prove that this organization has that route enabled.

### Anthropic, Google, and other native clients

Use the provider-specific Gateway snippet from Connect or the linked public
Gateway documentation for the selected region. Native
provider paths are not interchangeable: Anthropic, OpenAI Responses, Google,
Bedrock, and chat-completions routes have different URLs and request shapes.
Do not translate a native request into another protocol merely to make the
example compile.

## 4. Verify one real request

Explain that a live request sends its prompt to the selected provider through
Gateway and may incur usage charges. Use one small synthetic payload with no
application, customer, or secret data. An explicit request to configure and test
the selected route authorizes this bounded check; otherwise ask for approval
before sending it. Do not activate paid access or run production workloads as a test.

Run that request through the selected route. Check the
response and the application's normal error handling. A successful import,
configuration parse, or process exit is not proof that the request used the
Gateway.

If the project has a read-capable Logfire login, query the exact project for a
fresh Gateway request or open its Gateway activity view. Do not use the
send-only SDK write token for reads. If read verification is unavailable,
report the request response as verified and mark Logfire-side arrival as
unverified.

Run the project's formatter, type checker, build, and focused tests. Report the
exact provider, route, model, endpoint class, credential variable, request
result, and any unverified Logfire-side check. Never claim that a Gateway
request was observed when this session did not check it.

After setup, return the relevant project or Gateway view link. If provider
activation or another prerequisite prevents the request, report that blocker
and mark application inference as unverified.

## References

- [Pydantic AI Gateway documentation](https://pydantic.dev/docs/ai/overview/gateway/)

© pydantic · MIT · pydantic/skills

Similar skills

All skills for AI and ML →

From the same set24

The whole set →
migrating-mastra-to-pydantic-ai migrating-mastra-to-pydantic-ai — a skill that moves TypeScript Mastra apps to Python with Pydantic AI. Use it when source code imports @mastra/* or relies on Mastra agents, tools, workflows, memory, or streaming. CX Codex +1 464installs migrating-agno-to-pydantic-ai migrating-agno-to-pydantic-ai — a skill for Claude Code, Codex, Cursor and other platforms that migrates Python Agno applications to Pydantic AI. CX Codex +1 463installs logfire-coding-agents logfire-coding-agents — a skill for Claude Code that connects coding agent sessions to Logfire telemetry and routes model requests through Pydantic AI Gateway. CX Codex +1 239installs logfire-frontend logfire-frontend sets up browser observability and session replays for Pydantic Logfire in JavaScript and TypeScript applications. CX Codex +1 237installs logfire-codex-connection logfire-codex-connection — a Claude Code skill that connects Codex to Logfire, checks connection status, and stops session recording. Runs when managing Codex telemetry and session logging. CX Codex +1 235installs migrating-deep-agents-to-pydantic-ai-harness The migrating-deep-agents-to-pydantic-ai-harness Claude Code skill moves Python LangChain Deep Agents apps to Pydantic AI and Pydantic AI Harness. It applies when Deep Agents middleware, memory, subagent, or sandbox contracts matter. CX Codex +1 234installs pydantic-ai A Claude plugin that steers Claude toward correct Pydantic AI code: patterns, decision trees and notes on common pitfalls. ★ 156repo stars logfire Brings Pydantic Logfire observability to Python code and Claude Code sessions. Sets up framework instrumentation, MCP trace queries, and debugging workflows. ★ 156repo stars

Project sponsors

Companies that keep this analytics open