Helicone: an open source LLM observability platform and AI gateway you can self-host

What Helicone logs that your application does not

A chat completion call returns text and a usage object. It does not tell you which prompt version produced it, what the request cost at the moment it ran, how long the provider took versus your own code, or which earlier call in the same agent loop set up the context. Helicone's stated purpose is to capture that layer. The README describes logging requests from OpenAI, Anthropic, LangChain, Gemini and the Vercel AI SDK, then inspecting traces and sessions for agents, chatbots and document pipelines. The audience is AI engineers running LLM calls in production who need per-request accounting rather than aggregate dashboard numbers. The repository topics point the same direction: llm-cost, llm-evaluation, prompt-management, agent-monitoring. This is not a model host and not a vector store. It sits between your code and the provider.

The proxy path and the five services behind it

There are two ways traffic reaches Helicone. The first is the gateway: you point an OpenAI-compatible client at https://ai-gateway.helicone.ai with a Helicone API key, and the platform forwards to the underlying provider. The README states this gives access to 100+ models through one key, with intelligent routing and automatic fallbacks. The second is direct logging of calls you already make to a provider.

Self-hosting changes the shape considerably. The README lists the components: Web (NextJS frontend), Worker (proxy logging on Cloudflare Workers), Jawn (an Express and Tsoa server that collects logs), Supabase for the application database and auth, ClickHouse for analytics, and Minio for object storage. The Dockerfile confirms the split at build time, installing PostgreSQL 17 alongside the ClickHouse server image and running Flyway migrations from supabase/migrations and supabase/migrations_without_supabase. Request logs land in ClickHouse, relational state and auth in Postgres, and the frontend reads through Jawn. That is a six-process footprint before you have logged a single call, and it is the main reason the hosted option exists.

Installing Helicone with Docker Compose

The README gives a self-host quick start built on a compose script. Clone the repository, move into the docker directory, copy the example environment file, then run the compose wrapper. The script name and the subcommand are exactly as the README shows them.

# Clone the repository
git clone https://github.com/Helicone/helicone.git
cd docker
cp .env.example .env

# Start the services
./helicone-compose.sh helicone up

The .env.example at the repository root shows the variables the stack expects. Database access is a Postgres URL with the default local port, Supabase points at localhost:54321, and the Jawn service is reachable at http://localhost:8585. If you change ports in the compose file, these values have to change with them.

DATABASE_URL="postgresql://postgres:postgres@localhost:54322/postgres"
NEXT_PUBLIC_SUPABASE_URL="http://localhost:54321"
NEXT_PUBLIC_HELICONE_JAWN_SERVICE="http://localhost:8585"
NEXT_PUBLIC_APP_URL="https://us.helicone.ai"

For a first real request against the cloud gateway rather than the self-hosted stack, the README's TypeScript example swaps the base URL and the key. Nothing else in the client changes, which is the whole point of the OpenAI-compatible surface.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }]
});

After that call, the README says logs appear in the dashboard. If the request succeeds but nothing shows up, the failure is usually in the logging path, not the model call: check that the API key belongs to the same organization you are viewing.

Where the self-hosted deployment gets expensive

The README is direct that manual deployment is not recommended, and that is the right call. The Dockerfile installs PostgreSQL 17, Python 3.11, a JRE, Flyway 10.5.0 and the ClickHouse server in one image, then runs supervisord to keep the processes alive. That is a development convenience, not a production topology. Running it this way means a single container holds your analytics database, your relational database and your migration tooling, so a crash takes all three down together.

The Helm chart is the stated path for enterprise workloads, and the README says to contact [email protected] to get access. That is a real constraint: the production-grade deployment route is not in the public repository. If your organization cannot adopt a chart it cannot inspect, the compose path is what you have, and you should size it accordingly. There is also no documented rollback procedure in the README for a failed upgrade, and Flyway migrations against Postgres are forward-only by default. Back up the Postgres volume before pulling a new release.

Helicone compared with Langfuse and LiteLLM

The two comparisons that come up most are Langfuse and LiteLLM, and they split along a clean line. Langfuse is an observability and evaluation tool with SDK instrumentation; you add its client to your code and it records traces. Helicone's primary integration is the proxy: you change a base URL and the logging happens at the network boundary, which means it captures calls you did not instrument and cannot easily forget to instrument. The trade-off is that a proxy sees only what passes through it. Code paths that call a provider directly, or that run in an environment where you cannot change the endpoint, stay invisible.

LiteLLM is closer to Helicone's gateway half. It is a proxy that normalizes many providers behind an OpenAI-compatible API. Helicone does that too, but pairs it with the storage and UI layer: ClickHouse-backed analytics, sessions, traces, prompt versioning and a playground. If you only need provider normalization and already have your own logging, LiteLLM covers the routing job without the database footprint. If you need the routing and the queryable history together, Helicone is the combined option.

Licence, maintenance and upgrade cost

The repository is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files. That matters here because the self-host path copies migrations and application code into your own infrastructure. The licence does not cover the hosted service, the enterprise Helm chart, or the fine-tuning partners named in the README (OpenPipe and Autonomi). Nothing in the repository grants rights to those.

On maintenance, the last push to the default branch was on 2026-08-31, and the most recent tagged release is v2025.08.21-1 from 2025-08-21. The release tags are dated, so pinning to a tag rather than tracking main is the safer default. Upgrades run through Flyway against Postgres and through the ClickHouse migration directory, both of which are forward-only in the Dockerfile's configuration. The practical cost of an upgrade is the backup and verification window around those migrations, not the image pull.

Prompt versioning and the playground

Prompt management is the feature most likely to be underestimated. The README says prompts are versioned using production data and deployed through the AI Gateway without code changes, and that prompts remain under your control. The mechanism is that the gateway resolves the prompt at request time, so a prompt edit is a configuration change rather than a deploy. That is genuinely useful for teams where a prompt tweak currently requires a release.

It also concentrates risk. If prompt resolution happens in the gateway, the gateway is now on the critical path for every request, and a bad prompt version can be served to production traffic without a code review gate. The README does not document a staged rollout or approval flow for prompt versions. Treat the version history as the safety net and verify what the rollback behaviour actually is in your deployment before you rely on it.

Editorial conclusion

Adopt Helicone if you already send traffic to OpenAI, Anthropic or LangChain and want per-request cost, latency and trace data without building a logging pipeline. Skip it if you need a single-binary collector or cannot operate PostgreSQL, ClickHouse and object storage. Before committing, verify the self-host stack actually starts on your host: clone the repository, copy docker/.env.example to .env, run ./helicone-compose.sh helicone up, and confirm the Jawn service answers on NEXT_PUBLIC_HELICONE_JAWN_SERVICE (http://localhost:8585 in the example env).

Frequently asked questions

Official sources

1. Helicone/helicone on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases