LibreChat Balance Manager

Admin dashboard for managing LibreChat user token balances. View, search, top up, and bulk-manage user credits.

Features

• Dashboard — overview stats (total users, average balance, zero-balance users)
• All Balances — paginated table sorted by credits, with per-user Top Up / Set actions
• Find User — search by name or email (type "dave" to find daveporter@...) with instant results
• Bulk Operations — add tokens to all users or set everyone to a specific amount
• Preset Amounts — quick buttons for 100K, 500K, 1M, 2M, 5M tokens
• CSV Export — download balance data from the All Balances view
• API Key Auth — simple key-based authentication

Install on Dev Server

1. Copy files to the server

scp -r /path/to/Balance-Manager root@optical-librechat-dev:/opt/Balance-Manager

Or clone/pull from your repo if you've pushed it.

2. Create the .env file

cd /opt/Balance-Manager
cp .env.example .env
nano .env

Set your values:

MONGO_URI=mongodb://mongodb:27017/LibreChat
PORT=3002
API_KEY=your-secure-key-here

• MONGO_URI — points to the LibreChat MongoDB container (uses Docker network name mongodb)
• API_KEY — whatever secret key you want; you'll enter this in the browser on first load

3. Build and start

cd /opt/Balance-Manager
docker compose up -d --build

4. Verify it's running

docker logs librechat-balance-manager

You should see:

Connected to MongoDB
Balance Manager running on http://localhost:3002

5. Access the dashboard

The app runs on port 3002 (localhost only by default).

Option A — Direct access (if port is open):

http://your-server-ip:3002

To expose externally, change 127.0.0.1:3002:3002 to 0.0.0.0:3002:3002 in docker-compose.yml.

Option B — Add to NGINX (recommended):

Add this to your NGINX config (/opt/LibreChat/client/nginx.conf) inside the server block:

location /balance-manager/ {
    proxy_pass http://balance-manager:3002/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Then restart NGINX:

docker restart LibreChat-NGINX

Access at: https://chat-dev.oliver.solutions/balance-manager/

Note: If using the NGINX route, the balance-manager container must be on the same Docker network. This is already configured in docker-compose.yml via the librechat_default external network.

6. Add to LibreChat's docker-compose.override.yml (optional)

If you'd prefer to manage it alongside LibreChat instead of as a separate compose project, add this service to /opt/LibreChat/docker-compose.override.yml:

  balance-manager:
    build: /opt/Balance-Manager
    container_name: librechat-balance-manager
    ports:
      - "127.0.0.1:3002:3002"
    env_file:
      - /opt/Balance-Manager/.env
    restart: unless-stopped

Updating

cd /opt/Balance-Manager
docker compose down
docker compose up -d --build

Troubleshooting

Container won't connect to MongoDB:

Check that the container is on the librechat_default network:

docker network inspect librechat_default | grep balance

If not listed, make sure the network section in docker-compose.yml has:

networks:
  librechat_default:
    external: true

Port conflict:

Change the port in both .env (PORT=3003) and docker-compose.yml (127.0.0.1:3003:3003).

Reset API key in browser:

Open browser console and run:

localStorage.removeItem('bm_api_key')

Then refresh the page.