librechat-balances/README.md

# 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

```bash
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

```bash
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

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

### 4. Verify it's running

```bash
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:

```nginx
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:

```bash
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`:

```yaml
  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

```bash
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:

```bash
docker network inspect librechat_default | grep balance
```

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

```yaml
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:

```js
localStorage.removeItem('bm_api_key')
```

Then refresh the page.