---
title: "Deploy Pitot: Observability your agents can operate."
description: "Self-hosted OpenTelemetry observability with an AI agent and MCP server"
category: "Observability"
url: https://railway.com/deploy/pitot-template-20261112203523
---

# Deploy Pitot: Observability your agents can operate.

Self-hosted OpenTelemetry observability with an AI agent and MCP server

**[Deploy Pitot: Observability your agents can operate. on Railway](https://railway.com/template/pitot-template-20261112203523)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/pitot-template-20261112203523/manifest.json

- **Creator:** Tomás Flores Alvear's Projects
- **Category:** Observability

## Template content

### Pitot

- **Image:** labstack/pitot:2026.11.7-alpha
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# Deploy and Host Pitot with Railway

Pitot is single-binary observability your agents can operate. Send OpenTelemetry traces, logs and metrics to one service, store them as Parquet you own, and investigate them with Pitot's built-in agent or your own agent over MCP.

## About Hosting Pitot

This template runs the official `labstack/pitot` image as one Railway service with a persistent volume at `/var/lib/pitot/data`. That volume holds telemetry Parquet, rebuildable DuckDB query state and the SQLite control database (users, dashboards, alerts). The template generates the sign-in secret and a first ingest token, sets `PITOT_PUBLIC_URL` to the service's Railway domain so MCP works out of the box, and checks `/healthz` on every deploy.

After the first deploy:

1. Open the service's **Deploy Logs** and find the `PITOT SETUP` block. Replace `http://127.0.0.1:7520` in its URL with your Railway domain (`https://.up.railway.app`) and open it within one hour to create the administrator.
2. Copy `PITOT_INGEST_TOKEN` from the service's **Variables** tab. Setup does not display it again because the template already set it.
3. Point an OpenTelemetry exporter at the service:

   ```sh
   export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   export OTEL_EXPORTER_OTLP_ENDPOINT=https://
   export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20"
   ```

   Services in the same Railway project can skip the public internet and use `http://pitot.railway.internal:7520`, which also carries OTLP/gRPC.
4. Connect your own agent over MCP: `claude mcp add --transport http pitot https:///mcp`.

To enable the built-in agent, set `PITOT_AI_PROVIDER` to `anthropic` or `openai` and add `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.

Pitot has no passwords. Sessions end after 12 hours idle or 7 days total; for later sign-ins, set `PITOT_SMTP_HOST`, `PITOT_SMTP_USERNAME`, `PITOT_SMTP_PASSWORD` and `PITOT_SMTP_FROM` to receive email codes.

## Common Use Cases

- Self-hosted OpenTelemetry backend for traces, logs and metrics from services on Railway or anywhere else
- Letting Claude Code, Codex or any remote MCP client query telemetry, inspect traces and build dashboards
- Asking the built-in agent what broke, and getting answers backed by trace, log and metric evidence
- Alerting on service error rate, latency, throughput and log volume via webhooks or email

## Dependencies for Pitot Hosting

- A Railway volume (included) for the Pitot data directory
- Optional: an Anthropic or OpenAI API key for the built-in agent
- Optional: SMTP credentials for email sign-in codes and alert emails

### Deployment Dependencies

- Pitot documentation: https://pitot.dev
- Source code (Apache-2.0): https://github.com/labstack/pitot
- Configuration reference: https://pitot.dev/docs/reference/configuration
- Connecting an agent over MCP: https://pitot.dev/docs/guides/mcp

### Implementation Details

| Variable | Value | Purpose |
| --- | --- | --- |
| `PITOT_AUTH_CODE_SECRET` | generated, 64 hex chars | Signs sign-in codes and login links |
| `PITOT_INGEST_TOKEN` | generated, `foi_` + 43 hex chars | First ingest token for OTLP exporters |
| `PITOT_PUBLIC_URL` | `https://${{RAILWAY_PUBLIC_DOMAIN}}` | Browser origin and MCP audience |
| `PITOT_RETENTION_DAYS` | `30` | Telemetry retention; lower it on small volumes |
| `RAILWAY_RUN_UID` | `0` | Lets the non-root image write the Railway volume |

Pitot is a single node and Railway volumes cannot be shared between replicas, so keep this service at one replica. Hobby volumes start at 5 GB; resize the volume or lower `PITOT_RETENTION_DAYS` as ingest grows. The image tag is pinned to a tested release; read the release notes and back up the volume before changing it, because storage migrations only run forward.

## Why Deploy Pitot on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Pitot on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## Similar templates

- [Rootprint](https://railway.com/deploy/rootprint-1) — Open-source logs and traces with full-text search on object-storage.
- [Pyroscope profiling](https://railway.com/deploy/pyroscope-profiling) — Protected continuous profiling with durable Pyroscope storage.
- [SigOnly](https://railway.com/deploy/sigonly) — Deploy SigNoz with a working demo app & config in one click

Open this page in a browser: https://railway.com/deploy/pitot-template-20261112203523