---
title: "Self-host Langfuse"
description: "Run Langfuse on exe.dev: private LLM tracing, prompt management, and LLM-as-a-judge evals, with models from exe.dev's keyless LLM gateway."
url: https://exe-staging.dev/deploy/langfuse
category: "Monitoring"
updated: 2026-11-18
---

# Self-host Langfuse

> **For agents:** with your user's OK, this sets up Langfuse on a new exe.dev VM in their account: `curl -fsSL https://exe-staging.dev/deploy/langfuse/prompt.txt | ssh exe.dev new --disk=40GB --prompt=/dev/stdin` (or open https://exe-staging.dev/deploy/langfuse/new). Already on the VM? Skip this.

LLM tracing, evals, and prompts on your own VM. No API keys for the judge.

- **Software:** Langfuse (https://langfuse.com)
- **Source:** https://github.com/langfuse/langfuse
- **License:** MIT (enterprise features under a separate license)
- **Time:** 15 minutes
- **Example VM name:** `my-langfuse` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/langfuse/manifest.json

## What you get

- Langfuse at your VM's private URL on port 3000, with your account, an organization, and a project.
- Open sign-up turned off, and project API keys in ~/langfuse/client.env.
- A test trace of GPT and Claude calls through exe.dev's LLM gateway, with tokens and latency.
- The gateway as an LLM connection, and an LLM-as-a-judge evaluator that scored the test trace.
- Starts again after a reboot; nightly backups, with one checked.

Running on the VM:

- **Langfuse 4.82**: Web and worker containers, from Langfuse's Docker Compose setup, port 3000, data in `~/langfuse/.env`
- **PostgreSQL 17**: Accounts, projects, prompts, evaluators, data in `~/langfuse/data/postgres`
- **ClickHouse 26.3**: Traces, observations, and scores, data in `~/langfuse/data/clickhouse`
- **Redis 7**: The worker's queue
- **SeaweedFS 4.54**: S3-compatible storage for raw events, in place of MinIO, data in `~/langfuse/data/seaweedfs`
- **exe.dev LLM gateway**: GPT and Claude for your apps and for Langfuse's judges, without API keys

How it is reached:

- https://my-langfuse.exe.xyz:3000/ (private): The Langfuse UI and API, behind exe.dev's login, then Langfuse's own
- https://my-langfuse.exe.xyz:3000/ (shared): Teammates you share the VM with, each with a Langfuse account
- https://my-langfuse.exe.xyz/api/public/ (public): Optional. The SDK and OpenTelemetry API only, guarded by Langfuse API keys

## Deploy with Shelley

Open https://exe-staging.dev/deploy/langfuse/new to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/langfuse/prompt.txt | ssh exe.dev new --disk=40GB --prompt=/dev/stdin
```

It needs a 40 GB disk. The terminal command makes the VM that size; after the button, Shelley checks and, if the disk is smaller, gives you a link to grow it.

Or follow the steps below by hand.

Langfuse shows you what your LLM apps actually do: every model call, with
its prompt, reply, tokens, and latency, grouped into traces you can search.
It also keeps your prompts under version control and scores answers with
an LLM judge. Here it runs on your own exe.dev VM, so traces, which hold
your users' prompts, never leave a machine you control.

exe.dev does the parts that are usually a chore. The VM's disk keeps
PostgreSQL and ClickHouse across restarts. The UI is private behind your
exe.dev login before Langfuse's own sign-in even appears, and sharing it
is one command. Your apps and Langfuse's judges call models through
exe.dev's [LLM gateway](/docs/integrations-llm), with no API keys on any
VM. And Shelley can set it all up and wire tracing into your other apps.

<figure>
<img src="https://exe-staging.dev/deploy/langfuse/trace.png" alt="A Langfuse trace: an answer span with a GPT call and a Claude call through exe.dev's gateway, token counts, latency, and a helpfulness score of 1.00 from an LLM judge" width="1440" height="900" loading="lazy">
<figcaption>The test trace: GPT answers, Claude reviews, both through exe.dev's gateway. The judge's score is on the top span.</figcaption>
</figure>

## Open Langfuse

Open `https://my-langfuse.exe.xyz:3000/` (with your VM's name). Sign in to
exe.dev if you're asked, then sign in to Langfuse with your exe.dev email
and the password setup made for you. On the VM:

```bash
grep -E '^LANGFUSE_INIT_USER_(EMAIL|PASSWORD)=' ~/langfuse/.env
```

Save it in your password manager. You own an organization named after the
VM, with one project, `default`. Open **Tracing** to see the test trace
from setup, with a GPT call, a Claude call, and a `helpfulness` score.

Sign-up is turned off, so nobody else can make an account, even after you
share the VM. [Bring your team](#team) turns it on for the people you
choose.

## Trace an app on the VM

Setup left two things in `~/langfuse`: `client.env`, with the project's API
keys, and `hello_langfuse.py`, a small app that asks GPT a question and has
Claude review the answer, both through the gateway. Run it with a question
of your own:

```bash
cd ~/langfuse
set -a; . ./client.env; set +a
uv run hello_langfuse.py "What does a write-ahead log do?"
```

It prints a trace ID and the answer. The trace appears under **Tracing**
within a few seconds. The script shows the three usual ways in:

- **OpenAI SDK.** `from langfuse.openai import OpenAI` instead of
  `from openai import OpenAI`, with `base_url="https://llm.int.exe.xyz/v1"`.
  Every call becomes a generation with model, tokens, and latency.
- **Anthropic SDK.** Recent versions report their own OpenTelemetry spans; pass
  `open_telemetry={"traces": {"content_mode": "content"}}` to include
  prompts and replies, and `base_url="https://llm.int.exe.xyz"`.
- **`@observe()`.** Wraps any function in a span, so one request's calls
  land in one trace.

The Langfuse SDKs read `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and
`LANGFUSE_BASE_URL` from the environment, which is all `client.env` sets.
Apps on this VM use `http://localhost:3000`. Anything else that speaks
OpenTelemetry can send traces too:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/api/public/otel
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20$(printf %s "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64 -w0)"
```

Ask Shelley on another VM to "add Langfuse tracing to this app" and point
it at this page; it knows the gateway already.

<a id="other-machines"></a>

## Trace apps on other machines

Port 3000 is private, so a request from another VM or your laptop gets
exe.dev's `401` before it reaches Langfuse. Pick one of three ways in.

**From another exe.dev VM, with no token.** Give that VM a
[VM-to-VM integration](/docs/integrations-vm-to-vm) to Langfuse. On your
computer:

```bash
ssh exe.dev integrations add http-proxy --name=langfuse \
  --target=https://my-langfuse.exe.xyz:3000/ --peer --attach=vm:my-app
```

On `my-app`, set `LANGFUSE_BASE_URL=https://langfuse.int.exe.xyz` along with
the two keys. exe.dev adds a key at the network edge that `my-app` never sees, and
only the VMs you attach can use it.

**From your laptop or anywhere else, with a token.** Make a token that
opens this VM's HTTPS ports. On your computer:

```bash
ssh exe.dev ssh-key generate-api-key --vm=my-langfuse --label=langfuse-laptop --exp=1y
```

Send it in the `X-Exedev-Authorization` header, which exe.dev's proxy
checks and removes. With the Python SDK, keys in the environment as usual
and `LANGFUSE_BASE_URL=https://my-langfuse.exe.xyz:3000`:

```python
import os
from langfuse import Langfuse

langfuse = Langfuse(additional_headers={
    "X-Exedev-Authorization": "Bearer " + os.environ["EXE_VM_TOKEN"],
})
```

With plain OpenTelemetry, add it to the headers, after a comma:
`OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20...,X-Exedev-Authorization=Bearer%20$EXE_VM_TOKEN"`.
The token gets its holder past exe.dev's login to every port on this VM,
though not past Langfuse's. Keep it secret, add `--ips=` for a fixed
address, and revoke it with `ssh exe.dev ssh-key remove langfuse-laptop`.

**From servers you don't control, with a public door.** Some hosted
platforms can't add headers. Run a small Caddy proxy on port 8000 that
passes `/api/public/` and nothing else, and make only that port public.
On the VM:

```bash
cd ~/langfuse
cat > Caddyfile <<'EOF'
:8000 {
	handle /api/public/* {
		reverse_proxy langfuse-web:3000
	}
	handle {
		respond "Not found" 404
	}
}
EOF
cat > compose.override.yaml <<'EOF'
# A public, API-only door to Langfuse on port 8000. The UI and sign-in
# stay on port 3000, behind exe.dev's login.
services:
  ingest:
    image: docker.io/caddy:2.11
    restart: unless-stopped
    depends_on: [langfuse-web]
    ports:
      - "8000:8000"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
EOF
docker compose up -d
curl -fsS http://localhost:8000/api/public/health; echo
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/auth/sign-in
```

Expect a health line with the version, then `404`. On your computer:

```bash
ssh exe.dev share set-public my-langfuse
```

Apps then use `LANGFUSE_BASE_URL=https://my-langfuse.exe.xyz` and their keys.
Anyone on the internet can now reach Langfuse's public API, and its keys
are all that stands in the way. A public key and secret key pair can read
that project's traces and prompts as well as write them, so give each app
its own project when that matters, and rotate keys under **Settings → API
Keys**. `ssh exe.dev share set-private my-langfuse` closes the door again.

<a id="evals"></a>

## Score answers with an LLM judge

Setup added exe.dev's gateway as an LLM connection named `exe-gateway`,
and an evaluator, `helpfulness`, that asks `gpt-5.4-mini` to rate every
span named `answer` from 0 to 1, with a sentence of reasoning. That's how
the test trace got its score. Open **Evaluators** to see it, or **Scores**
for every score so far.

<figure>
<img src="https://exe-staging.dev/deploy/langfuse/evaluators.png" alt="Langfuse's Evaluators page, listing the helpfulness LLM-as-a-judge evaluator on gpt-5.4-mini, healthy, created through the API" width="1440" height="900" loading="lazy">
<figcaption>The judge setup made, running on the gateway's gpt-5.4-mini.</figcaption>
</figure>

For your own app, click **New evaluator** and start from a template such
as **Check Correctness**, or write your own prompt. Choose `exe-gateway`
and a model, map the template's variables to the observation's input and
output, and on the **Rules** tab pick which observations it runs on. Each
score is one model call from your LLM allocation, so sample busy apps with
a lower rate. **Set project default model** at the top makes `exe-gateway`
the choice for new evaluators. The gateway connection lists
`gpt-5.4-mini`, `gpt-5.5`, and `gpt-6-luna`; add other gateway models
under **Settings → LLM Connections**. The **Playground** uses the same
connection.

## Manage prompts

Keep prompts in Langfuse and your apps fetch them by name, so you can
change a prompt without a deploy. Each change is a new version; the
`production` label marks the one apps get. Linking a call to its prompt
version lets you compare versions in **Prompts**:

```python
from langfuse import get_client
from langfuse.openai import OpenAI

langfuse = get_client()
prompt = langfuse.get_prompt("explain")  # the production version, cached
gpt = OpenAI(base_url="https://llm.int.exe.xyz/v1", api_key="exe-llm-gateway")
reply = gpt.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": prompt.compile(topic="a write-ahead log")}],
    langfuse_prompt=prompt,
)
```

Create `explain` first under **Prompts → New prompt**, with the text
`Explain {{topic}} to a new engineer in two sentences.` and the
`production` label.

<a id="team"></a>

## Bring your team

exe.dev's login already sits in front of Langfuse, so its sign-up page is
safe to open to the people you share the VM with. On the VM, turn sign-up
on:

```bash
cd ~/langfuse
sed -i 's/^AUTH_DISABLE_SIGNUP=.*/AUTH_DISABLE_SIGNUP=false/' .env
docker compose up -d
```

Then, on your computer, share the VM:

```bash
ssh exe.dev share add my-langfuse teammate@example.com
```

They open the same URL, sign in to exe.dev, and click **Sign up** in
Langfuse. New accounts join your organization as members, with access to
its projects; change roles under **Settings → Organization Settings → Members**. Once everyone
has an account, set `AUTH_DISABLE_SIGNUP=true` again and run
`docker compose up -d`. `ssh exe.dev share remove my-langfuse teammate@example.com`
locks someone out at exe.dev's door; remove their Langfuse membership too.

## Keep your traces

Backups run nightly into `~/langfuse-backups`: a PostgreSQL dump plus
ClickHouse's traces and scores, the raw events, and `.env`. Keep a copy
**off the VM**. On your computer:

```bash
scp -r my-langfuse.exe.xyz:langfuse-backups .
```

Keep these files private: they hold your traces, and `.env` holds every
secret. To restore one or to update Langfuse, see the sections below, or
ask Shelley. Something stuck? On the VM, try
`cd ~/langfuse && docker compose ps` and
`docker compose logs --tail=100 langfuse-web langfuse-worker`.

## The nuts and bolts

Happy clicking Deploy? You can stop here. These are the same setup steps
Shelley follows, plus the maintenance commands for later.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Install by hand</summary>

### Create a VM

On your computer (pick another name if `my-langfuse` is taken):

```bash
ssh exe.dev new --name=my-langfuse --disk=40GB
ssh my-langfuse.exe.xyz
```

All remaining installation commands run **on the VM**, as `exedev`.
Commands use `hostname`, so your VM can have any name.

### Room on the disk

The images take about 5 GB, and traces and backups grow from there. Check
the disk:

```bash
df -h /
```

If **Size** is under 36G, the VM was made with a smaller disk. Grow it with
[this link](https://exe.dev/suggest?command=resize%20my-langfuse%20--disk%3D40GB)
(with your VM's name), or on your computer with
`ssh exe.dev resize my-langfuse --disk=40GB`. Then, back on the VM, grow the
filesystem to match:

```bash
sudo resize2fs "$(findmnt -no SOURCE /)"
df -h /
```

### Get Docker ready

Langfuse runs as six containers under Docker Compose. Enable Docker at
boot, or exe.dev's on-demand Docker won't restart Langfuse after a reboot.
Install `jq` and `uv` if needed:

```bash
sudo systemctl enable --now docker.service
systemctl is-enabled docker.service
command -v jq >/dev/null || sudo apt-get install -y jq
command -v uv >/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
```

The check should print `enabled`.

### Write the settings

This makes `~/langfuse/.env`, readable only by you, with random secrets,
the Langfuse version, the VM's URL, and the first account, organization,
project, and API keys. Langfuse creates those on its first start. It never
overwrites an existing `.env`:

```bash
mkdir -p ~/langfuse && cd ~/langfuse
if [ ! -e .env ]; then
  owner=$(curl -fsS https://reflection.int.exe.xyz/email | jq -r '.email // empty')
  touch .env && chmod 600 .env
  cat >> .env <<ENV
LANGFUSE_VERSION=4.82.0
NEXTAUTH_URL=https://$(hostname).exe.xyz:3000
NEXTAUTH_SECRET=$(openssl rand -hex 32)
SALT=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 24)
CLICKHOUSE_PASSWORD=$(openssl rand -hex 24)
REDIS_AUTH=$(openssl rand -hex 24)
S3_SECRET_KEY=$(openssl rand -hex 24)
AUTH_DISABLE_SIGNUP=true
LANGFUSE_INIT_ORG_ID=exe
LANGFUSE_INIT_ORG_NAME=$(hostname)
LANGFUSE_INIT_PROJECT_ID=default
LANGFUSE_INIT_PROJECT_NAME=default
LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-$(openssl rand -hex 16)
LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-$(openssl rand -hex 16)
LANGFUSE_INIT_USER_EMAIL=$owner
LANGFUSE_INIT_USER_NAME=${owner%@*}
LANGFUSE_INIT_USER_PASSWORD=Lf1-$(openssl rand -hex 12)
ENV
fi
grep -E '^(NEXTAUTH_URL|LANGFUSE_INIT_USER_EMAIL)=' .env
```

Check the URL has your VM's name and the email is yours. If the email is
empty, the reflection integration didn't answer: put the email you sign in
to exe.dev with after `LANGFUSE_INIT_USER_EMAIL=` and its first part after
`LANGFUSE_INIT_USER_NAME=`, with `nano .env`.

Save the project keys for the SDKs, and the S3 credentials for SeaweedFS:

```bash
cd ~/langfuse
(umask 077
 echo "LANGFUSE_BASE_URL=http://localhost:3000" > client.env
 sed -n 's/^LANGFUSE_INIT_PROJECT_PUBLIC_KEY=/LANGFUSE_PUBLIC_KEY=/p;
         s/^LANGFUSE_INIT_PROJECT_SECRET_KEY=/LANGFUSE_SECRET_KEY=/p' .env >> client.env
 s3_secret=$(sed -n 's/^S3_SECRET_KEY=//p' .env)
 cat > s3.json <<JSON
{
  "identities": [
    {
      "name": "langfuse",
      "credentials": [{"accessKey": "langfuse", "secretKey": "$s3_secret"}],
      "actions": ["Admin", "Read", "Write", "List", "Tagging"]
    }
  ]
}
JSON
)
cut -d= -f1 client.env
```

Expect the three variable names.

### Write the Compose file

This follows Langfuse's own
[docker-compose.yml](https://github.com/langfuse/langfuse/blob/main/docker-compose.yml),
with a pinned version, data in `~/langfuse/data`, only port 3000 open, and
SeaweedFS in place of MinIO, whose open-source repository is archived:

```bash
cd ~/langfuse
cat > compose.yaml <<'EOF'
# Langfuse v4 on one exe.dev VM: web, worker, PostgreSQL, ClickHouse,
# Redis, and SeaweedFS for S3. Based on Langfuse's docker-compose.yml.
# Secrets and settings come from .env in this directory.
name: langfuse

x-langfuse-env: &langfuse-env
  NEXTAUTH_URL: ${NEXTAUTH_URL}
  DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/postgres
  SALT: ${SALT}
  ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  TELEMETRY_ENABLED: "false"
  CLICKHOUSE_MIGRATION_URL: clickhouse://clickhouse:9000
  CLICKHOUSE_URL: http://clickhouse:8123
  CLICKHOUSE_USER: clickhouse
  CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
  CLICKHOUSE_CLUSTER_ENABLED: "false"
  REDIS_HOST: redis
  REDIS_PORT: "6379"
  REDIS_AUTH: ${REDIS_AUTH}
  # Raw events go to SeaweedFS, inside Docker's network.
  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
  LANGFUSE_S3_EVENT_UPLOAD_REGION: us-east-1
  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://seaweedfs:8333
  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: langfuse
  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
  # exe.dev's LLM gateway has a link-local address, which Langfuse refuses
  # for LLM connections unless the host is listed here.
  LANGFUSE_LLM_CONNECTION_WHITELISTED_HOST: llm.int.exe.xyz

services:
  langfuse-web:
    image: docker.langfuse.com/langfuse/langfuse:${LANGFUSE_VERSION}
    restart: unless-stopped
    depends_on: &depends
      postgres: { condition: service_healthy }
      clickhouse: { condition: service_healthy }
      redis: { condition: service_healthy }
      seaweedfs: { condition: service_healthy }
    ports:
      - "3000:3000"
    environment:
      <<: *langfuse-env
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
      AUTH_DISABLE_SIGNUP: ${AUTH_DISABLE_SIGNUP}
      # If you turn sign-up on for teammates, they join your organization.
      LANGFUSE_DEFAULT_ORG_ID: ${LANGFUSE_INIT_ORG_ID}
      LANGFUSE_DEFAULT_ORG_ROLE: MEMBER
      # First start: your organization, project, API keys, and account.
      LANGFUSE_INIT_ORG_ID: ${LANGFUSE_INIT_ORG_ID}
      LANGFUSE_INIT_ORG_NAME: ${LANGFUSE_INIT_ORG_NAME}
      LANGFUSE_INIT_PROJECT_ID: ${LANGFUSE_INIT_PROJECT_ID}
      LANGFUSE_INIT_PROJECT_NAME: ${LANGFUSE_INIT_PROJECT_NAME}
      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-}
      LANGFUSE_INIT_PROJECT_SECRET_KEY: ${LANGFUSE_INIT_PROJECT_SECRET_KEY:-}
      LANGFUSE_INIT_USER_EMAIL: ${LANGFUSE_INIT_USER_EMAIL:-}
      LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-}
      LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-}

  langfuse-worker:
    image: docker.langfuse.com/langfuse/langfuse-worker:${LANGFUSE_VERSION}
    restart: unless-stopped
    depends_on: *depends
    environment:
      <<: *langfuse-env

  postgres:
    image: docker.io/postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: postgres
      TZ: UTC
      PGTZ: UTC
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

  clickhouse:
    image: docker.io/clickhouse/clickhouse-server:26.3.62.3
    restart: unless-stopped
    user: "101:101"
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: clickhouse
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
    volumes:
      - ./data/clickhouse:/var/lib/clickhouse
      - ./data/clickhouse-logs:/var/log/clickhouse-server
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: docker.io/redis:7
    restart: unless-stopped
    command: --requirepass ${REDIS_AUTH} --maxmemory-policy noeviction
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 10s
      retries: 10

  seaweedfs:
    image: docker.io/chrislusf/seaweedfs:4.54
    restart: unless-stopped
    command: server -dir=/data -s3 -s3.config=/etc/seaweedfs/s3.json
    volumes:
      - ./data/seaweedfs:/data
      - ./s3.json:/etc/seaweedfs/s3.json:ro
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://127.0.0.1:8333/healthz || exit 1
      interval: 5s
      timeout: 5s
      retries: 20
EOF
mkdir -p data/postgres data/redis data/seaweedfs
sudo install -d -o 101 -g 101 data/clickhouse data/clickhouse-logs
docker compose config --quiet && echo config ok
```

Expect `config ok`. The VM is private, and only port 3000 is published,
so the databases are reachable from inside Docker's network alone.

### Start Langfuse

Start SeaweedFS first and make the bucket, then everything else. The first
pull downloads about 5 GB and takes a few minutes:

```bash
cd ~/langfuse
docker compose up -d --wait seaweedfs
docker compose exec -T seaweedfs sh -c 'echo s3.bucket.create -name langfuse | weed shell'
docker compose up -d
until curl -fs http://localhost:3000/api/public/health; do sleep 5; done; echo
docker compose ps --format '{{.Service}}: {{.Status}}'
```

Expect `{"status":"OK","version":"4.82.0"}` and six services `Up`,
four of them `(healthy)`. Langfuse runs its database migrations on the
first start, which takes a minute or two. Check sign-in and sign-up:

```bash
cd ~/langfuse
set -a; . ./client.env; set +a
curl -fsS -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  http://localhost:3000/api/public/projects | jq -c '[.data[].name]'
curl -sS -X POST http://localhost:3000/api/auth/signup -H 'Content-Type: application/json' \
  -d '{"name":"x","email":"x@example.com","password":"Not-allowed-1"}'; echo
```

Expect `["default"]`, then `{"message":"Sign up is disabled."}`.

### Send a test trace

Write the sample app:

```bash
cd ~/langfuse
cat > hello_langfuse.py <<'EOF'
# /// script
# requires-python = ">=3.10"
# dependencies = ["langfuse>=5,<6", "openai", "anthropic"]
# ///
"""A tiny two-model app, traced in Langfuse.

GPT answers a question through exe.dev's LLM gateway (via Langfuse's
drop-in OpenAI client), then Claude reviews the answer through the same
gateway (the Anthropic SDK reports its own OpenTelemetry spans). Both calls
land in one Langfuse trace, with tokens and latency.

Needs LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL.
"""
import os
import sys

from anthropic import Anthropic
from langfuse import get_client, observe
from langfuse.openai import OpenAI

# exe.dev's gateway needs no key; the SDKs want a value anyway.
GATEWAY = os.environ.get("LLM_GATEWAY", "https://llm.int.exe.xyz")
gpt = OpenAI(base_url=GATEWAY + "/v1", api_key="exe-llm-gateway")
# The Anthropic SDK traces its own calls; "content" adds prompts and replies.
claude = Anthropic(
    base_url=GATEWAY,
    api_key="exe-llm-gateway",
    open_telemetry={"traces": {"content_mode": "content"}},
)


@observe()
def answer(question: str) -> str:
    draft = gpt.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": question + " Answer in two sentences."}],
    ).choices[0].message.content
    review = claude.messages.create(
        model="claude-haiku-4-5",
        max_tokens=200,
        messages=[{"role": "user", "content": f"In one sentence, is this answer correct?\n\n{draft}"}],
    ).content[0].text
    print("Trace ID:", get_client().get_current_trace_id())
    return f"{draft}\n\nReview: {review}"


if __name__ == "__main__":
    question = " ".join(sys.argv[1:]) or "Why is the sky blue?"
    print(answer(question))
    get_client().flush()  # send the trace before exiting
EOF
```

The judge comes before the first real trace, so that trace gets a score.
Add the gateway as an LLM connection, then the `helpfulness` evaluator and
a rule that runs it on spans named `answer`:

```bash
cd ~/langfuse
set -a; . ./client.env; set +a
auth="$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY"
api=http://localhost:3000/api/public
curl -fsS -X PUT "$api/llm-connections" -u "$auth" -H 'Content-Type: application/json' \
  -d '{"provider": "exe-gateway", "adapter": "openai",
       "baseURL": "https://llm.int.exe.xyz/v1", "secretKey": "exe-llm-gateway",
       "customModels": ["gpt-5.4-mini", "gpt-5.5", "gpt-6-luna"],
       "withDefaultModels": false}' | jq -c '{provider, baseURL}'
evaluator=$(curl -fsS -X POST "$api/v2/evaluators" -u "$auth" -H 'Content-Type: application/json' -d '{
  "name": "helpfulness", "type": "llm_as_judge",
  "prompt": "Rate how helpful this answer is to the question.\n\nQuestion: {{input}}\n\nAnswer: {{output}}",
  "modelConfig": {"provider": "exe-gateway", "model": "gpt-5.4-mini"},
  "outputDefinition": {"dataType": "NUMERIC", "minValue": 0, "maxValue": 1,
    "scoreReasoningInstructions": "One or two sentences on why.",
    "scoreValueInstructions": "0 is unhelpful, 1 is fully helpful."}}' | jq -r .id)
curl -fsS -X POST "$api/v2/evaluation-rules" -u "$auth" -H 'Content-Type: application/json' -d '{
  "name": "helpfulness on answers", "enabled": true, "sampling": 1,
  "filter": [{"type": "stringOptions", "column": "name", "operator": "any of", "value": ["answer"]}],
  "evaluatorAssignments": [{"evaluatorId": "'"$evaluator"'", "variableMapping": [
    {"variable": "input", "source": "input"}, {"variable": "output", "source": "output"}]}]}' \
  | jq -c '{name, enabled}'
```

Expect the connection, then the rule, enabled. Now run the app, wait for
the judge, and read back the trace and its score:

```bash
cd ~/langfuse
set -a; . ./client.env; set +a
trace=$(uv run hello_langfuse.py "What does a write-ahead log do?" | sed -n 's/^Trace ID: //p')
echo "trace $trace"
sleep 20
curl -fsS -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_BASE_URL/api/public/v2/observations?traceId=$trace&fields=core,basic,model,usage" \
  | jq -c '.data[] | {name, model, tokens: .usageDetails.total}'
set -a; . ./.env; set +a
docker compose exec -T clickhouse clickhouse-client --user clickhouse --password "$CLICKHOUSE_PASSWORD" \
  -q "select name, value, comment from scores where trace_id = '$trace' format Vertical"
```

Expect three observations: `answer`, an `OpenAI-generation` on a
`gpt-5.4-mini` model, and `anthropic.messages.create` on a Claude Haiku
model, with token counts. Then a `helpfulness` score near `1` with the judge's reason.
If the score is missing, wait a few seconds and run the last command again.

### Set up nightly backups

The backup script dumps PostgreSQL, then stops ClickHouse and the worker
for the few seconds it takes to copy their files. Langfuse keeps taking
traces meanwhile, and the worker catches up when it's back:

```bash
cd ~/langfuse
cat > backup.sh <<'EOF'
#!/bin/sh
# Back up Langfuse: a PostgreSQL dump, plus a tarball of ClickHouse
# (traces, scores), SeaweedFS (raw events), .env, and the Compose files.
# Run with sudo.
set -eu
cd "$(dirname "$0")"
owner=$(stat -c %u:%g .)
backups=$(dirname "$PWD")/langfuse-backups
out=$backups/langfuse-$(date -u +%Y%m%d-%H%M%S)
mkdir -p "$out"
chmod 700 "$backups" "$out"
docker compose exec -T postgres pg_dump -U postgres -Fc postgres > "$out/postgres.dump"
# A short stop keeps ClickHouse's files consistent. The web container keeps
# taking traces meanwhile; they wait in S3 and Redis for the worker.
docker compose stop langfuse-worker clickhouse
trap 'docker compose start clickhouse langfuse-worker' EXIT
tar -czf "$out/data.tar.gz" --exclude=./data/postgres \
  --exclude=./data/redis --exclude=./data/clickhouse-logs .
chmod 600 "$out"/*
chown -R "$owner" "$backups"
# Keep the 7 newest backups.
ls -1d "$backups"/langfuse-*/ | head -n -7 | xargs -r rm -rf
echo "Backed up to $out"
EOF
chmod 755 backup.sh
sudo tee /etc/systemd/system/langfuse-backup.service >/dev/null <<EOF
[Unit]
Description=Back up Langfuse to ~/langfuse-backups
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
ExecStart=$HOME/langfuse/backup.sh
EOF
sudo tee /etc/systemd/system/langfuse-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Langfuse every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now langfuse-backup.timer
sudo systemctl start langfuse-backup.service
systemctl list-timers langfuse-backup.timer
ls -lh ~/langfuse-backups/*/
docker compose ps --format '{{.Service}}: {{.Status}}'
```

Check that the timer has a next run, the backup has `postgres.dump` and
`data.tar.gz`, and all six services are up again. For failures:
`journalctl -u langfuse-backup.service`.

### Test a backup

Unpack the newest backup into a **scratch directory** and start a spare
ClickHouse on its copy, without touching the running one:

```bash
latest=$(ls -1d ~/langfuse-backups/langfuse-*/ | tail -n 1)
mkdir /tmp/langfuse-restore-test && cd /tmp/langfuse-restore-test
sudo tar -xzf "$latest/data.tar.gz"
docker run --rm -i postgres:17 pg_restore --list < "$latest/postgres.dump" | grep -c 'TABLE DATA'
docker run -d --name langfuse-restore-test --user 101:101 \
  -v "$PWD/data/clickhouse:/var/lib/clickhouse" clickhouse/clickhouse-server:26.3.62.3
sleep 10
docker exec langfuse-restore-test clickhouse-client -q 'select count() from default.scores'
docker rm -f langfuse-restore-test
cd ~ && sudo rm -rf /tmp/langfuse-restore-test
```

Expect a table count from the PostgreSQL dump (around 80) and at least `1`
score. The last two lines remove only the scratch copy.

Installation done. Leave sharing and the public door to the owner; continue
with [Open Langfuse](#open-langfuse).

</details>

<details id="back-up-and-restore" class="dp-details">
<summary>Back up and restore</summary>

On the VM, `sudo ~/langfuse/backup.sh` makes an extra backup and prints its
path. Copy backups off the VM as shown in [Keep your traces](#keep-your-traces).

### Restore

On a new VM, get Docker ready as in [Install](#get-docker-ready). Create
`~/langfuse-backups` there, then copy a backup over from your computer:

```bash
scp -r langfuse-backups/langfuse-20261118-033012 my-langfuse.exe.xyz:langfuse-backups/
```

Use your backup's actual name here and below. All remaining commands run
**on the VM**. If Langfuse already runs there, stop it and keep its
directory aside first:

```bash
cd ~/langfuse && docker compose down
sudo mv ~/langfuse ~/langfuse.before-restore
```

Unpack the backup, load PostgreSQL before Langfuse starts, then start
everything:

```bash
backup=~/langfuse-backups/langfuse-20261118-033012
mkdir ~/langfuse && cd ~/langfuse
sudo tar -xzf "$backup/data.tar.gz"
mkdir -p data/postgres data/redis
sudo install -d -o 101 -g 101 data/clickhouse-logs
docker compose up -d --wait postgres
docker compose exec -T postgres pg_restore -U postgres -d postgres --clean --if-exists < "$backup/postgres.dump"
docker compose up -d
until curl -fs http://localhost:3000/api/public/health; do sleep 5; done; echo
```

If the VM's name changed, set `NEXTAUTH_URL` in `.env` to the new URL and
run `docker compose up -d` again. Sign in and check your traces are there.
On a new VM, recreate the backup timer from
[Install](#set-up-nightly-backups). Keep `~/langfuse.before-restore` until
you're happy everything is back.

</details>

<details id="update" class="dp-details">
<summary>Update Langfuse</summary>

`LANGFUSE_VERSION` in `.env` pins the release. Langfuse ships often; read
the [changelog](https://github.com/langfuse/langfuse/releases), then on the
VM back up, set the new version, and restart:

```bash
cd ~/langfuse
sudo ./backup.sh
sed -i 's/^LANGFUSE_VERSION=.*/LANGFUSE_VERSION=4.83.0/' .env
docker compose pull
docker compose up -d
until curl -fs http://localhost:3000/api/public/health; do sleep 5; done; echo
docker image prune -f
```

Use the version you want in place of `4.83.0`. Langfuse migrates its
databases on start; the health line shows the new version when it's done.
To roll back, [restore the backup](#restore): an older version won't run
on migrated databases. Your apps' SDKs update separately; this setup needs
Python SDK 3 or later and JS/TS SDK 4 or later.

PostgreSQL, ClickHouse, Redis, and SeaweedFS are pinned in `compose.yaml`.
When Langfuse's own
[docker-compose.yml](https://github.com/langfuse/langfuse/blob/main/docker-compose.yml)
moves to a newer ClickHouse, change the tag here to match. Don't change
PostgreSQL's major version in place; that needs a dump and restore.

</details>

<details id="troubleshooting" class="dp-details">
<summary>Something not working?</summary>

**The page says 401 or shows exe.dev's login.** That's exe.dev's proxy:
sign in to exe.dev with an account the VM is shared with. From scripts, use
one of the ways in [Trace apps on other machines](#other-machines).

**Sign-in loops back to the sign-in page.** `NEXTAUTH_URL` in `.env` must
be exactly the URL in your browser, `https://<vm>.exe.xyz:3000`. Fix it and
run `docker compose up -d`.

**Traces don't show up.** Short scripts must call `flush()` before they
exit. Check the keys belong to this project, and look for errors with
`docker compose logs --tail=100 langfuse-worker`.

**An evaluator fails with a blocked or invalid URL.** The
`LANGFUSE_LLM_CONNECTION_WHITELISTED_HOST` line must be in `compose.yaml`
for both containers, as above. Run `docker compose up -d` after adding it.

**A container keeps restarting.** `docker compose ps` shows which one, and
`docker compose logs --tail=100 <service>` why. ClickHouse needs its data
directories owned by user 101; recreate them with the `sudo install` line
from [Install](#write-the-compose-file).

**The disk is filling up.** `df -h /` and `sudo du -sh ~/langfuse/data/*`.
Trim old backups, or grow the disk with `ssh exe.dev resize`.

</details>

## Frequently asked questions

### How much does it cost?

Langfuse's open-source edition is free. You pay for your [VM plan](https://exe.dev/pricing), and your apps' model calls and Langfuse's judges use your exe.dev [LLM allocation](/docs/integrations-llm). Tracing itself makes no model calls.

### What size VM do I need?

The whole stack idles at about 2.5 GB of memory, so a default VM is fine to start, with a 40 GB disk for the 5 GB of images, your traces, and a week of backups. Langfuse suggests 4 CPUs and 16 GB for heavy production traffic; grow the VM with `ssh exe.dev resize`.

### Who can see my traces?

Only people you share the VM with get past exe.dev's login, and they still need a Langfuse account. Traces hold your apps' prompts and replies, so treat them like your app's data. The optional public door opens the API only, and every call there needs a project's secret key.

### Why not MinIO?

MinIO's open-source repository was archived in April 2026. This recipe uses SeaweedFS, which Langfuse lists as a supported S3 store and uses in its Helm chart. Any S3-compatible store works, including a bucket from a cloud provider.

### Why is the cost column empty?

Langfuse prices calls by model name, and it has no prices for some of the gateway's names. Add them under **Settings → Model Definitions** if you want cost estimates. Token counts and latency are always there.

### Does it work with LangChain, the Vercel AI SDK, LiteLLM, and the rest?

Yes. Langfuse takes OpenTelemetry, so anything with a Langfuse integration or OpenTelemetry instrumentation can send traces here. Use your VM's URL as the host and add exe.dev's header as shown in [Trace apps on other machines](#other-machines).

### Can I upload images and files with traces?

Not with this setup. Langfuse's media uploads go straight from your app to the S3 store, which stays inside the VM here. Text, token counts, and metadata all work.


## Related

- [Self-host Open WebUI](https://exe-staging.dev/deploy/open-webui.md): A private ChatGPT for you and your team. No API keys.
- [Self-host Grafana and Prometheus](https://exe-staging.dev/deploy/grafana.md): Dashboards and alerts for every VM you run, signed in with exe.dev.
- [Give agents API access without giving them the keys](https://exe-staging.dev/deploy/agent-secrets.md): Your agents call your APIs. The keys stay with exe.dev, outside the VM.
- [Deploy a Docker Compose app from GitHub](https://exe-staging.dev/deploy/docker-compose.md): Your compose.yaml on a VM of its own. git push to deploy.
- [Self-host PostgreSQL](https://exe-staging.dev/deploy/postgres.md): Your own Postgres on a real disk, with backups you've actually restored.
- [Self-host Uptime Kuma](https://exe-staging.dev/deploy/uptime-kuma.md): A little lookout for your websites. Green bars encouraged.
