lago Documentation

File: README.md Copy Chapter

See Lago price an AI workload Copy Chapter

Run the maintained demo from this repository:

./examples/agentic-ai-demo/run.sh

It starts the Lago version that matches this checkout, creates a disposable local organization, and prices three illustrative AI requests. Each request sends one input-token event and one output-token event:

3 AI requests
5,000 input tokens  x $0.000002 = $0.01
1,250 output tokens x $0.000008 = $0.01
Lago usage total                   = $0.02

Docker Compose starts an isolated Lago service, then a small script seeds and verifies the example through Lago's API. It retrieves current usage, independently reconciles the result, and retries one transaction to confirm that usage does not increase. Everything stays on your machine; the demo does not access Lago Cloud. The bundled credentials and API key are disposable and only intended for this local demo.

Log into http://localhost:8080 with [email protected] / agentic-ai-demo-local-password, then open Customers → Agentic AI Demo Customer → Agentic AI Demo subscription → Usage.

Requirements: Docker, curl, and jq. If ports 8080 or 3001 are occupied, set LAGO_DEMO_UI_PORT and LAGO_DEMO_API_PORT before running. The demo keeps Lago running so you can inspect the customer, metrics, plan, subscription, events, and usage in the UI. Remove its isolated Compose project and data volume when you are done:

./examples/agentic-ai-demo/run.sh --cleanup

Use Claude Code, Codex, or Cursor

Open this repository in your coding agent and paste:

Run Lago's maintained Agentic AI demo by following this README. Keep it local;
do not modify source files or unrelated Docker resources. When it passes, give
me the UI URL, token usage and charges, idempotency evidence, and cleanup
command. Then offer to connect this agent to Lago's local MCP server.

What is Lago? Copy Chapter

Lago is the programmable system between product usage and revenue. Send events from your application, turn them into billable metrics, apply pricing and entitlements, then generate invoices and collect payments.

Usage events -> Metering -> Pricing and credits -> Entitlements -> Invoices -> Payments -> Revenue

Use Lago to launch and change pricing without rebuilding billing:

• tokens by model, input, output, cache, reasoning, or tool call
• GPU, CPU, storage, and other compute consumption
• API calls, transactions, seats, active users, or custom events
• prepaid credits with automatic top-ups
• subscriptions with allowances, minimum commitments, and overages
• self-serve plans and negotiated enterprise contracts in the same system

Lago is headless and API-first. Your application, internal tools, and agents use the same billing primitives through the REST API, SDKs, webhooks, and MCP server. Product, finance, and operations teams can use the Lago UI when a human interface is faster.

How Lago fits into your stack Copy Chapter

Lago keeps metering and pricing independent from payment processing. Connect Stripe, Adyen, GoCardless, or another provider without making its product catalog your source of truth.

Lago Direct and Lago Embedded Copy Chapter

The same Lago engine supports two operating models:

Lago Direct is the standard way to use Lago: send your own product usage, model your pricing, and bill your customers. Lago Embedded uses the same primitives to let platforms, marketplaces, AI builders, fintech products, and developer tools offer metering and billing to their customers.

Both models start with Lago's open-source billing engine and can be paired with Premium deployment, customization, security, and support options. With Lago Embedded, you control the customer experience and which capabilities your users can access.

Agentic-first by design Copy Chapter

Agentic-first means Lago's billing model is available as structured, inspectable interfaces instead of being trapped in a dashboard.

The MCP server exposes read and write tools and inherits the permissions of its Lago API key. Treat agent credentials as privileged, control who can access the agent, review tool calls, and keep human confirmation around sensitive billing changes.

Platform Copy Chapter

Explore metering, billing and invoicing, entitlements, cash collection, revenue analytics, and integrations.

Production characteristics Copy Chapter

• Idempotent ingestion. Lago deduplicates usage events by transaction_id, so retrying an event does not bill it twice. Read the ingestion guide.
• Atomic batches. If one event in a batch is invalid, Lago rejects the batch and persists none of its events. Read the batch API reference.
• Asynchronous processing. Dedicated workers can isolate events, billing, payments, invoices, webhooks, PDFs, alerts, and analytics as volume grows. Review the architecture.
• Observable operation. Lago exposes Prometheus metrics for APIs, queues, workers, events, billing, webhooks, and dependencies. Review monitoring.
• Deployment control. Run Lago locally, in your cloud, or on your infrastructure. Production deployments can separate and scale stateful services and workers independently.
• Security. Lago is SOC 2 Type II certified and supports self-hosting for teams that need infrastructure and data control. Review security.

Chosen by teams operating at scale Copy Chapter

Mistral AI, Groq, PayPal, Synthesia, Blacksmith, and other teams have publicly selected Lago for billing. The figures below describe the companies using Lago, not volume processed by Lago.

Sources for company context: Mistral AI, Groq, Blacksmith, Synthesia, and PayPal.

Open source and managed options Copy Chapter

Deploy Lago Copy Chapter

For a source-based local deployment:

git clone --depth 1 https://github.com/getlago/lago.git
cd lago

echo "LAGO_RSA_PRIVATE_KEY=\"$(openssl genrsa 2048 | openssl base64 -A)\"" >> .env
docker compose up -d

Use the self-hosted deployment guide for persistent storage, SMTP, TLS, object storage, Redis, database configuration, and upgrades. For larger deployments, use the Lago Helm charts and configure dedicated workers.

SDKs and developer resources Copy Chapter

• Getting started
• API reference
• OpenAPI specification
• Pricing templates
• Architecture
• Monitoring
• Changelog
• Public roadmap
• System status

Contributing Copy Chapter

Lago is built in the open. Read the contributing guide and development environment setup to get started.

Look for issues labeled beginner or help-wanted, or join the Lago Slack community.

License Copy Chapter

The Lago platform is distributed under the AGPLv3 license. Read why Lago chose AGPLv3. Lago's Agent SDKs and MCP server are distributed from separate repositories under the MIT license.

Analytics and tracking Copy Chapter

Self-hosted Lago instances collect basic product analytics by default. Lago does not collect customer PII or financial data through this tracking. Review what is collected or opt out.

File: deploy/README.md Copy Chapter

Lago Deploy

This repository contains the necessary files to deploy the Lago project.

Docker Compose Local Copy Chapter

To deploy the project locally, you need to have Docker and Docker Compose installed on your machine.
This configuration can be used for small production usages but it's not recommended for large scale deployments.

Get Started Copy Section

1. Get the docker compose file

curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.local.yml

2. Run the following command to start the project:

docker compose up --profile all

# If you want to run it in the background
docker compose up -d --profile all

Docker Compose Light Copy Chapter

This configuration provide Traefik as a reverse proxy to ease your deployment.
It supports SSL with Let's Encrypt. :warning: You need a valid domain (with at least one A or AAA record)!

1. Get the docker compose file

curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.light.yml
curl -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.light.example

2. Replace the .env values with yours

LAGO_DOMAIN=domain.tld
[email protected]

3. Run the following command to start the project

docker compose up --profile all

# If you want to run it in the background
docker compose up -d --profile all

Docker Compose Production Copy Chapter

This configuration provide Traefik as a reverse proxy to ease your deployment.
It supports SSL wth Let's Encrypt. :warning: You need a valid domain (with at least one A or AAA record)!
It also adds multiple services that will help your to handle more load.
Portainer is also packed to help you scale services and manage your Lago stack.

curl -o docker-compose.yml https://raw.githubusercontent.com/getlago/lago/main/deploy/docker-compose.production.yml
curl -o .env https://raw.githubusercontent.com/getlago/lago/main/deploy/.env.production.example

2. Replace the .env values with yours

LAGO_DOMAIN=domain.tld
[email protected]
PORTAINER_USER=lago
PORTAINER_PASSWORD=changeme

3. Run the following command to start the project

docker compose up --profile all

# If you want to run it in the background
docker compose up -d --profile all

Configuration Copy Chapter

Profiles Copy Section

The docker compose file contains multiple profiles to enable or disable some services.
Here are the available profiles:

• all: Enable all services
• all-no-pg: Disable the PostgreSQL service
• all-no-redis: Disable the Redis service
• all-no-keys: Disable the RSA keys generation service

This allow you to start only the service you want to use, please see the following sections for more information.

# Start all services
docker compose up --profile all

# Start without PostgreSQL
docker compose up --profile all-no-pg

# Start without Redis
docker compose up --profile all-no-redis

# Start without PostgreSQL and Redis
docker compose up --profile all-no-db

# Start without RSA keys generation
docker compose up --profile all-no-keys

# Start without PostgreSQL, Redis and RSA keys generation
docker compose up

PostgreSQL Copy Section

It is possible to disable the usage of the PostgreSQL database to use an external database instance.

1. Set those environment variables:

• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_DB
• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_SCHEMA optional

2. Run the following command to start the project without PostgreSQL:

docker compose up --profile all-no-pg

Redis Copy Section

It is possible to disable the usage of the Redis database to use an external Redis instance.

1. Set those environment variables:

• REDIS_HOST
• REDIS_PORT
• REDIS_PASSWORD optional

2. Run the following command to start the project without Redis:

docker compose up --profile all-no-redis

RSA Keys Copy Section

Those docker compose file generates an RSA Keys pair for the JWT tokens generation.
You can find the keys in the lago_rsa_data volume or in the /app/config/keys directory in the backends containers.
If you do not want to use those keys:

• Remove the lago_rsa_data volume
• Generate your own key using openssl genrsa 2048 | openssl base64 -A
• Export this generated key to the LAGO_RSA_PRIVATE_KEY env var.
• Run the following command to start the project without the RSA keys generation:

docker compose up --profile all-no-keys

All BE Services use the same RSA key, they will exit immediately if no key is provided.

Monitoring Copy Chapter

For production deployments, we recommend setting up monitoring for Sidekiq workers. See the Monitoring documentation for:

• Prometheus metrics endpoints and available metrics
• Recommended alerting rules
• Grafana dashboard recommendations

File: docker/README.md Copy Chapter

Lago Docker Image

This is the official one docker image for Lago.

This docker image is designed for testing and staging environments only. It is not recommended for production use due to its simplified architecture and resource constraints. For production deployments, please refer to our deployment guides in the deploy folder or use our helm chart for a more robust and scalable setup.

Features Copy Chapter

This docker image embed everything to run Lago with just one command line to ease the deployment.
Here are the services that are running into the container :

• PostgreSQL
• Redis
• Lago UI
• Lago API
• Lago Worker
• Lago Clock
• PDF Service (optional)

Get Started Copy Chapter

docker run -d --name lago -p 80:80 -p 3000:3000 getlago/lago:latest

PDF generation is disabled by default. We use Gotenberg, which is only available as a Docker image. To enable PDF generation, use the following command:

docker run -d --name lago -v /var/run/docker.sock:/var/run/docker.sock -p 80:80 -p 3000:3000 getlago/lago:latest

You will see an other docker container named lago-pdf running.

Using External Services Copy Chapter

You can use external services for the database and Redis instance.
Here are the env var you should pass to the container to use them :

Storage Copy Chapter

The container is using a volume to store the data, you can mount it to your host to keep the data safe.
You can find many folders for each services in the /data folder.

SSL Copy Chapter

SSL is disabled by default in this development/staging image. To enable SSL support when using a proxy or load balancer:

For new installations:

• Add the environment variable LAGO_DISABLE_SSL=false when running the container
  bash Copy

  docker run -e LAGO_DISABLE_SSL=false ...

For existing installations:

• Navigate to your /data volume
• Edit the .env file to change LAGO_DISABLE_SSL=true to LAGO_DISABLE_SSL=false

:warning: Note that this only enables SSL support - you must still configure SSL certificates and termination through your reverse proxy or load balancer.

Logs Copy Chapter

Database Logs (creation, migration) are stored in the /data/db.log file.
Applicative logs are streamed to the standard output.

Contributing Copy Chapter

This docker image is a work in progress.
Feel free to open issues or PRs to improve it or ask for new features.

File: events-processor/README.md Copy Chapter

Lago Events Processor

High throughput events processor for Lago.
This service is in charge of providing a post-process for events in high volume scenarios.

This service need to be configured with Clickhouse and Redpanda. Please contact us for further informations.

How to run it Copy Chapter

With the docker compose environment:

go build -o event_processors .

./event_processors

Development Copy Chapter

Running Copy Section

lago up -d events-processor

Testing Copy Section

lago exec events-processor go test ./...

Configuration Copy Chapter

This app requires some env vars

Additionally there's a few optional environment variables