Skip to main content

Getting Started with Loopers

Loopers is a tool that helps you control how much money you spend on AI. It works like a smart guard for your wallet. When your application wants to talk to an AI service, it sends the request to Loopers first. Loopers checks if you have enough money left in your budget. If you do, it forwards the request. If you do not, it stops the request immediately to prevent you from spending too much.

This guide will help you get set up and protected in under five minutes.

Prerequisites​

Before starting, you will need:

  • Go 1.25 or higher (required when building from source)
  • Docker and Docker Compose (recommended for running Redis)

This is the fastest way to run Loopers in production or local development without installing Go.

Step 1: Get the Docker Compose file​

git clone https://github.com/CURSED-ME/loopers-oss.git
cd loopers-oss

Step 2: Start Redis and the Proxy​

Start both the proxy server and the Redis database in the background:

docker-compose up -d

Step 3: Create a proxy key​

Create a security key for your application. This key replaces your real AI provider key in your code:

docker-compose exec loopers /app/loopers keys create --name mykey --provider openai

Write down your raw key. It starts with lp and is only shown once. Copy it immediately.

Step 4: Set a budget limit​

Configure how much this key is allowed to spend:

docker-compose exec loopers /app/loopers budget set KEY_HASH --minute 0.50 --hourly 2.00 --daily 10.00 --weekly 50.00 --monthly 150.00

All spending limits are optional. The first limit you reach will block any further requests.

Step 5: Route your first request​

Point your application at the Loopers proxy:

curl -X POST http://localhost:8080/openai/v1/chat/completions \
  -H "Authorization: Bearer RAW_LP_KEY" \
  -H "X-Loopers-Provider-Key: YOUR_REAL_OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello Loopers"}]}'

Alternatively, use path-based auth for agents (like opencode or codex) that don't support custom headers:

macOS / Linux:

curl -X POST http://localhost:8080/RAW_LP_KEY/openai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_REAL_OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello Loopers"}]}'

Windows (PowerShell):

Invoke-RestMethod -Method Post -Uri "http://localhost:8080/RAW_LP_KEY/openai/v1/chat/completions" `
  -Headers @{"Authorization"="Bearer YOUR_REAL_OPENAI_KEY"; "Content-Type"="application/json"} `
  -Body '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello Loopers"}]}'

Method 2: Native Installation (Go 1.25+)​

If you want to run the proxy natively on your machine or just use the CLI wrapper for agents (loopers exec).

Step 1: Install the CLI globally​

macOS / Linux / Windows:

go install github.com/CURSED-ME/loopers-oss/cmd/loopers@latest

Step 2: Initialize Configuration​

This creates a loopers.yaml configuration file and a docker-compose.yml (for Redis) in your current directory.

loopers init

Step 3: Start Redis​

Start only the Redis container in the background:

docker-compose up -d redis

Note: If you already have Redis running locally (e.g. via Homebrew, apt, or a remote instance), you can skip this step. Just make sure the redis.addr in your loopers.yaml points to your existing Redis instance.

[!WARNING] The default Redis password in the generated docker-compose.yml was recently updated from changeme_in_production to demo-pass. If you generated your compose file in an older version, make sure the REDIS_PASSWORD in docker-compose.yml matches redis.password in your loopers.yaml.

Step 4: Start the Proxy Server​

Start the server in development mode (without TLS):

macOS / Linux:

SERVER_INSECURE_DEV=true loopers serve

Windows (PowerShell):

$env:SERVER_INSECURE_DEV="true"; loopers serve

Step 5: Create a Key and Route Requests​

In a new terminal window, you can now run Loopers commands directly against your local proxy:

loopers keys create --name mykey --provider openai

Next Steps​