How to Intermediate · 4 min read

How to self-host Langfuse

Quick answer
To self-host Langfuse, deploy its open-source backend by cloning the langfuse/langfuse GitHub repository and running the backend services with Docker or Kubernetes. Then configure your Langfuse Python SDK or client to point to your self-hosted endpoint for AI observability and tracing.

PREREQUISITES

  • Python 3.8+
  • Docker or Kubernetes installed
  • Git installed
  • Langfuse API key or self-hosted credentials
  • pip install langfuse

Setup

Start by cloning the official langfuse/langfuse GitHub repository, which contains the backend source code and deployment manifests. Install Docker or Kubernetes to run the backend services locally or in your cloud environment. Set environment variables for your Langfuse API key or self-hosted credentials.

bash
git clone https://github.com/langfuse/langfuse.git
cd langfuse
# For local Docker deployment
./scripts/docker-up.sh

# Or deploy on Kubernetes
kubectl apply -f k8s/deployment.yaml

# Install Langfuse Python SDK
pip install langfuse

Step by step

Run the Langfuse backend services using Docker Compose or Kubernetes. Then configure the Python Langfuse client to connect to your self-hosted backend by specifying the host URL and your API keys. Use the client to instrument your AI calls and capture observability data.

python
import os
from langfuse import Langfuse

# Set environment variables for your self-hosted Langfuse
os.environ["LANGFUSE_PUBLIC_KEY"] = "your-public-key"
os.environ["LANGFUSE_SECRET_KEY"] = "your-secret-key"

# Initialize Langfuse client with self-hosted endpoint
langfuse = Langfuse(
    public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
    secret_key=os.environ["LANGFUSE_SECRET_KEY"],
    host="http://localhost:3000"  # Replace with your backend URL
)

# Example: instrument a function call
@langfuse.observe()
def call_ai_model(prompt: str) -> str:
    # Simulate AI call
    return f"Response to: {prompt}"

result = call_ai_model("Hello Langfuse")
print("AI call result:", result)
output
AI call result: Response to: Hello Langfuse

Common variations

You can run the Langfuse backend on different platforms such as bare metal, cloud VMs, or Kubernetes clusters. The Python SDK supports async instrumentation and integration with OpenAI or other AI clients. Customize the host parameter to point to your self-hosted URL. For advanced tracing, use the @observe() decorator or manual context management.

python
import asyncio
from langfuse import Langfuse

async def main():
    langfuse = Langfuse(
        public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
        secret_key=os.environ["LANGFUSE_SECRET_KEY"],
        host="http://localhost:3000"
    )

    @langfuse.observe()
    async def async_ai_call(prompt: str) -> str:
        await asyncio.sleep(0.1)  # Simulate async call
        return f"Async response to: {prompt}"

    result = await async_ai_call("Async Langfuse")
    print("Async AI call result:", result)

asyncio.run(main())
output
Async AI call result: Async response to: Async Langfuse

Troubleshooting

  • If the client cannot connect, verify your host URL and that the backend services are running.
  • Check Docker or Kubernetes logs for backend errors.
  • Ensure your LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are correctly set and match the backend configuration.
  • For network issues, confirm firewall or proxy settings allow traffic to your Langfuse backend.

Key Takeaways

  • Clone and deploy the Langfuse backend from GitHub using Docker or Kubernetes for self-hosting.
  • Configure the Langfuse Python SDK with your self-hosted backend URL and API keys for observability.
  • Use the @observe() decorator to instrument AI calls and capture detailed traces.
  • Support for async instrumentation and multiple deployment environments enables flexible integration.
  • Verify backend service status and environment variables to troubleshoot connection issues.
Verified 2026-04
Verify ↗