---
title: "Deploy Breadcrumb"
description: "Simple, self-hosted LLM observability for TypeScript"
category: "Observability"
url: https://railway.com/deploy/breadcrumb
---

# Deploy Breadcrumb

Simple, self-hosted LLM observability for TypeScript

**[Deploy Breadcrumb on Railway](https://railway.com/template/breadcrumb)**

- **Creator:** My Projects
- **Category:** Observability
- **Total deploys:** 7

## Template content

### breadcrumb https://breadcrumb.sh/favicon.svg

- **Source:** https://github.com/joshuaKnauber/breadcrumb
- **Health check:** /health
- **Public domain:** Yes

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

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

### ClickHouse https://devicons.railway.app/ClickHouse?variant=light

- **Image:** clickhouse/clickhouse-server:25.8
- **Start command:** `bash -c 'echo "<clickhouse><custom_settings_prefixes>SQL_</custom_settings_prefixes></clickhouse>" > /etc/clickhouse-server/config.d/custom.xml && /entrypoint.sh'`
- **Health check:** /ping
- **Public domain:** Yes

## Documentation

# Deploy and Host Breadcrumb on Railway

Breadcrumb is an open-source LLM observability platform for TypeScript. It traces your AI agents and LLM pipelines, capturing prompts, completions, token counts, latency, and costs per call. Self-hosted, so your data stays on your infrastructure. Instrument your code in three lines with the TypeScript SDK.

## About Hosting Breadcrumb

Breadcrumb runs three services: a Hono HTTP server that handles trace ingestion, authentication, and a tRPC API; a PostgreSQL database for projects and API keys; and a ClickHouse instance for high-volume trace and span analytics. The React dashboard is bundled with the server.

To deploy, you need to provision PostgreSQL and ClickHouse instances, set environment variables for database connections and a JWT secret, and run database migrations. Railway handles all three services in a single project, so you can connect them through internal networking without exposing databases to the public internet.

## Common Use Cases

- **Debug failing AI agents** - Trace every step of a multi-step LLM pipeline to pinpoint where prompts go wrong, tokens spike, or responses degrade
- **Track LLM costs across projects** - Monitor token usage and cost per trace to catch expensive calls before they blow through your budget
- **Audit prompt and completion history** - Log every prompt sent and response received for compliance, QA, or fine-tuning dataset collection

## Dependencies for Breadcrumb Hosting

- **PostgreSQL 16** - Stores projects, API keys, user accounts, and session data
- **ClickHouse 24** - Stores trace and span time-series data for fast analytical queries
- **Node.js 20+** - Runtime for the Breadcrumb server

### Deployment Dependencies

- [Breadcrumb GitHub Repository](https://github.com/jknauber/breadcrumb)
- [Breadcrumb TypeScript SDK (`@breadcrumb-sdk/core`)](https://www.npmjs.com/package/@breadcrumb-sdk/core)
- [ClickHouse on Railway](https://railway.app/template/clickhouse)
- [PostgreSQL on Railway](https://railway.app/template/postgres)

### Implementation Details

Once deployed, install the SDK in your application and start tracing:

```typescript
import { Breadcrumb } from "@breadcrumb-sdk/core";

const bc = Breadcrumb.init({
  apiKey: "your-api-key",
  url: "https://your-breadcrumb-instance.railway.app",
});

const trace = bc.trace("my-agent");
const span = trace.span("llm-call", { model: "claude-sonnet-4-20250514" });
// ... your LLM call
span.end({ inputTokens: 150, outputTokens: 320 });
trace.end();
```

For Vercel AI SDK users, Breadcrumb provides a drop-in telemetry helper that captures `generateText`, `streamText`, and `generateObject` calls automatically.

## Why Deploy Breadcrumb 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 Breadcrumb 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

- [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
- [Unwrapped Spotify Music Stats](https://railway.com/deploy/wide-bold) — Unwrapped Spotify Music Stats, Estatísticas de músicas disponíveis

Open this page in a browser: https://railway.com/deploy/breadcrumb