---
title: "Deploy Pydantic AI"
description: "A typed AI agent runtime with web chat and persistent memory."
category: "AI/ML"
url: https://railway.com/deploy/pydantic-ai
---

# Deploy Pydantic AI

A typed AI agent runtime with web chat and persistent memory.

**[Deploy Pydantic AI on Railway](https://railway.com/template/pydantic-ai)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/pydantic-ai/manifest.json

- **Creator:** INF Labs
- **Category:** AI/ML

## Template content

### Pydantic AI https://avatars.githubusercontent.com/u/110818415?s=60&v=4

- **Source:** codestorm-official/pydantic-ai
- **Public domain:** Yes

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# Deploy and Host Pydantic AI on Railway

Pydantic AI is a typed Python framework for building reliable AI agents with structured outputs, multi-provider model support, tool integration, and production-focused application patterns.

This Railway template deploys a ready-to-use **Pydantic AI agent runtime with a built-in web chat interface and PostgreSQL-backed persistent conversation memory**.

## About Hosting Pydantic AI

This template provides a lightweight production-oriented Pydantic AI deployment that runs as a FastAPI application.

The application includes a browser-based chat interface, REST API endpoints, multi-provider model configuration, persistent conversation history, and PostgreSQL storage.

Unlike a stateless demo chatbot, conversations are stored in PostgreSQL using Pydantic AI's native message history format, allowing conversations to survive application restarts and redeployments.

## Common Use Cases

* Build and host AI assistants
* Create persistent AI chat applications
* Build internal AI tools
* Prototype Pydantic AI agents
* Expose AI agents through REST APIs
* Run multi-provider AI applications
* Build typed AI backends
* Experiment with structured AI agent workflows
* Add persistent conversation memory to AI applications
* Self-host an AI chat interface with your own provider credentials

## Dependencies for Pydantic AI Hosting

This template includes:

* **Pydantic AI** — Typed AI agent runtime
* **FastAPI** — HTTP API and web application layer
* **PostgreSQL** — Persistent conversation history
* **Railway Private Networking** — Internal database connectivity

Redis is not required.

The Pydantic AI application itself does not require a persistent volume because conversation state is stored in PostgreSQL.

## Features

* Built-in web chat interface
* Persistent multi-turn conversations
* PostgreSQL-backed conversation history
* OpenAI support
* Anthropic support
* Google Gemini support
* Groq support
* Configurable system prompt
* FastAPI REST API
* OpenAPI documentation
* Health checks
* Optional Bearer-token API protection
* Configurable PostgreSQL connection pool
* Non-root Docker runtime
* Reproducible builds using `uv.lock`

## Persistent Conversation Memory

Conversation history is stored in PostgreSQL using Pydantic AI's native message representation.

Each conversation is assigned a UUID and stores:

* User messages
* Assistant responses
* Pydantic AI message metadata
* Creation timestamp
* Last update timestamp

When the browser reloads, the application restores the active conversation from PostgreSQL automatically.

This means chat history survives:

* Browser refreshes
* Application restarts
* Railway redeployments
* Container replacement

The Pydantic AI service itself remains stateless.

## Supported AI Providers

The template supports multiple model providers.

| Provider  | Environment Variable | Example Model            |
| --------- | -------------------- | ------------------------ |
| OpenAI    | `OPENAI_API_KEY`     | `gpt-4o-mini`            |
| Anthropic | `ANTHROPIC_API_KEY`  | `claude-sonnet-4`        |
| Google    | `GOOGLE_API_KEY`     | `gemini-2.5-flash`       |
| Groq      | `GROQ_API_KEY`       | Provider-supported model |

Select the provider using:

```text
MODEL_PROVIDER
```

and configure the model using:

```text
MODEL_NAME
```

Only the API key for the selected provider is required for chat requests.

## Important Environment Variables

### Database

`DATABASE_URL`

Required PostgreSQL connection string used for persistent conversation history.

This template automatically references the PostgreSQL service through Railway service variables.

### Model Configuration

`MODEL_PROVIDER`

Selects the active AI provider.

Supported values:

* `openai`
* `anthropic`
* `google`
* `groq`

`MODEL_NAME`

Defines the model used by the selected provider.

### Provider Credentials

Depending on the selected provider, configure one of:

* `OPENAI_API_KEY`
* `ANTHROPIC_API_KEY`
* `GOOGLE_API_KEY`
* `GROQ_API_KEY`

Provider keys are optional at application startup, but chat requests require the key corresponding to the selected provider.

### System Prompt

`SYSTEM_PROMPT`

Optional instructions applied to every agent run.

### API Protection

`APP_API_KEY`

Optional Bearer token used to protect chat and conversation API endpoints.

If left empty, the built-in browser chat works without API authentication.

If configured, API clients must send:

```text
Authorization: Bearer YOUR_API_KEY
```

### Database Pool

Optional PostgreSQL tuning variables:

* `DB_POOL_MIN_SIZE`
* `DB_POOL_MAX_SIZE`
* `DB_POOL_TIMEOUT`

The defaults are suitable for small Railway deployments.

## Web Interface

The built-in web interface is available at:

```text
/
```

After Railway assigns a public domain, open:

```text
https://your-pydantic-ai-domain.up.railway.app/
```

The interface includes:

* Persistent chat history
* New Chat button
* Active provider and model display
* Conversation restoration after refresh
* Mobile-responsive layout
* Error handling for missing provider keys and backend failures

No separate frontend service is required.

## API Endpoints

### Health

```text
GET /health
```

Healthy response:

```json
{
  "status": "ok",
  "database": "ok"
}
```

The health endpoint checks PostgreSQL connectivity but does not call an LLM provider.

### Configuration

```text
GET /api/config
```

Returns the active provider and model configuration without exposing API keys.

### Chat

```text
POST /api/chat
```

Example request:

```json
{
  "message": "Hello"
}
```

Example response:

```json
{
  "response": "Hello! How can I help?",
  "conversation_id": "11111111-2222-3333-4444-555555555555",
  "model": "gpt-4o-mini",
  "provider": "openai"
}
```

To continue an existing conversation:

```json
{
  "message": "What did I ask you earlier?",
  "conversation_id": "11111111-2222-3333-4444-555555555555"
}
```

### Create Conversation

```text
POST /api/conversations
```

### Get Conversation

```text
GET /api/conversations/{conversation_id}
```

### Delete Conversation

```text
DELETE /api/conversations/{conversation_id}
```

## OpenAPI Documentation

FastAPI automatically provides interactive API documentation at:

```text
/docs
```

Example:

```text
https://your-pydantic-ai-domain.up.railway.app/docs
```

## Railway Deployment

This template deploys two services:

```text
Internet
   │
   ▼
Railway HTTPS
   │
   ▼
Pydantic AI
   :8000
      │
      │ Railway Private Network
      ▼
PostgreSQL
   :5432
```

### Pydantic AI

Recommended settings:

* Public Domain: enabled
* Port: `8000`
* Health Check: `/health`
* Persistent Volume: not required
* Custom Start Command: not required
* `RAILWAY_RUN_UID`: not required

### PostgreSQL

Recommended settings:

* Public Domain: disabled
* Private networking: enabled
* Port: `5432`
* Persistent volume: required

The Pydantic AI service connects to PostgreSQL using:

```text
${{Postgres.DATABASE_URL}}
```

## After Deployment

1. Wait for PostgreSQL to become available.
2. Wait for the Pydantic AI service to become healthy.
3. Generate a public domain for the Pydantic AI service on port `8000`.
4. Configure your preferred `MODEL_PROVIDER`.
5. Configure `MODEL_NAME`.
6. Add the API key for the selected model provider.
7. Open the public URL.
8. Send your first message.
9. Refresh the browser and verify that the conversation is restored.
10. Optionally configure `APP_API_KEY` for external API clients.

## Security Notes

For production deployments:

* Keep PostgreSQL private
* Never expose provider API keys to frontend applications
* Do not expose `DATABASE_URL`
* Use `APP_API_KEY` when external clients need protected API access
* Rotate credentials if exposed
* Use scoped provider credentials where supported
* Review persisted conversations before storing sensitive information
* Keep detailed application logs free of secrets

The built-in browser UI intentionally uses safe text rendering rather than injecting model output as raw HTML.

## Pydantic AI vs Alternatives

| Feature                          | Pydantic AI | Agno | Mastra |        CrewAI |
| -------------------------------- | ----------: | ---: | -----: | ------------: |
| Python-native                    |           ✅ |    ✅ |      ❌ |             ✅ |
| Typed outputs                    |           ✅ |    ✅ |     ⚠️ |            ⚠️ |
| Built-in web UI in this template |           ✅ |    ✅ |      ✅ |            ⚠️ |
| Persistent PostgreSQL memory     |           ✅ |    ✅ |      ✅ | App-dependent |
| Multi-provider models            |           ✅ |    ✅ |      ✅ |             ✅ |
| REST API                         |           ✅ |    ✅ |      ✅ | App-dependent |
| Agent framework                  |           ✅ |    ✅ |      ✅ |             ✅ |
| MCP support                      |           ✅ |    ✅ |      ✅ |             ✅ |
| Structured validation            |           ✅ |    ✅ |     ⚠️ |            ⚠️ |
| Self-hosted                      |           ✅ |    ✅ |      ✅ |             ✅ |
| Lightweight deployment           |           ✅ |    ✅ |      ✅ |             ✅ |

Pydantic AI is especially well suited for developers who want strongly typed AI applications using Python and Pydantic-style validation.

## Why Deploy Pydantic AI on Railway?

Railway provides a straightforward environment for running both the application runtime and PostgreSQL persistence layer.

Deploying Pydantic AI on Railway provides:

* Automatic HTTPS domains
* Persistent PostgreSQL storage
* Private database networking
* Simple environment variable management
* Built-in deployment logs
* Easy redeployments
* No application volume requirement
* No Redis dependency
* A ready-to-use web chat interface
* Persistent multi-turn AI conversations
* Multi-provider model flexibility

## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/pydantic-ai