> ## Documentation Index
> Fetch the complete documentation index at: https://evakage.docs.thesteau.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure access, capacity, and temporary delivery.

For Docker, edit the `.env` file beside your Compose file and recreate the container after changes:

```bash theme={null}
docker compose up -d --force-recreate
```

When running from source with `npm run dev` or `npm start`, set environment variables in your shell. These commands do not load `app/.env`.

## Server and access

| Variable | Default | Purpose |
| - | - | - |
| `PORT` | `3000` | Server port |
| `HOST` | `0.0.0.0` | Listen address |
| `AUTH_TOKEN` | Unset | Require a token to access the app |
| `DEVICE_ALLOWLIST` | Unset | Allow only listed full device fingerprints |
| `ALLOWED_ORIGINS` | Same host | Allowed WebSocket origins, comma-separated |
| `TRUST_PROXY` | `0` | Trust forwarded host and client-IP headers |
| `ICE_SERVERS_JSON` | `[]` | STUN/TURN servers as a JSON array |

With `AUTH_TOKEN` set, open `https://host/?token=THE_TOKEN` once to establish an access cookie. The health endpoint remains open.

For `DEVICE_ALLOWLIST`, copy full fingerprints from the QR icon in Devices (**Connection details**) or **Known devices**. Devices must prove they hold the matching key. Remove a fingerprint and restart to revoke access.

If direct connections fail across networks or firewalls, configure TURN. Encrypted server relay remains the fallback.

## HTTPS reverse proxies

Set `TRUST_PROXY=1` only behind a proxy you control.

* Keep the backend port private.
* Preserve the public `Host` header or send `X-Forwarded-Host`, including any non-default port.
* Account changes require an HTTPS Origin matching that host. Account cookies are Secure.
* `ALLOWED_ORIGINS` affects WebSockets, not the account origin check.

If signup shows **“Same-origin JSON request required”**, check these settings first.

## Device and room limits

| Variable | Default | Purpose |
| - | - | - |
| `MAX_DEVICES` | `200` | Connected registered device identities |
| `MAX_ROOMS` | `50` | Active rooms across the server |
| `ROOM_MAX_MEMBERS` | `20` | Members per room; allowed range 2–64 |

Reconnecting an existing device does not use an extra slot. Each account can own two rooms; creating a third replaces its oldest room. Rooms with more than six members use the server relay, including members whose seats are temporarily held while they are offline.

## File and text budgets

Byte limits include encrypted content and envelopes. Accepted uploads reserve their declared size.

| Variable | Default | Purpose |
| - | - | - |
| `MAX_FILE_BYTES` | `536870912` (512 MiB) | Maximum size of one file |
| `BLOB_STORE_BYTES` | `4294967296` (4 GiB) | Total relay budget |
| `BLOB_TEXT_RESERVE_BYTES` | `1073741824` (1 GiB) | Separate text budget; capped at one quarter of the total |
| `BLOB_CHAT_FILE_BYTES` | `53687091200` (50 GiB) | Per-chat file ceiling |
| `BLOB_CHAT_TEXT_BYTES` | `1073741824` (1 GiB) | Per-chat text ceiling |
| `BLOB_PER_DEVICE` | `32` | Pending files per sender |
| `BLOB_MESSAGES_PER_DEVICE` | `2000` | Pending messages per sender |

The smaller global budgets take precedence over per-chat ceilings. Files cannot consume the text budget.

When a budget is full, the server may remove older items of the same kind whose uploads are complete but which are still waiting for recipients. Active uploads and downloads are protected from capacity cleanup. Online participants receive warnings and removal notices.

## Relay expiry

| Variable | Default | Purpose |
| - | - | - |
| `BLOB_IDLE_GRACE_MS` | `900000` (15 min) | Grace after everyone disconnects |
| `BLOB_SOLO_MAX_MS` | `10800000` (3 hours) | Expiry for a direct chat with only one device online; also how long a disconnected room member keeps a seat |
| `BLOB_MAX_AGE_MS` | `259200000` (3 days) | Maximum item age |
| `BLOB_SWEEP_MS` | `60000` (1 min) | Physical cleanup interval |

Rooms are exempt from the one-device expiry rule. Self-chat has a 24-hour offline window and a maximum age of three days. See [relay lifetimes](/guides/transfers#how-long-server-copies-last).

## Storage paths

| Variable | Docker default | Purpose |
| - | - | - |
| `ACCOUNTS_DB` | `/home/node/evakage-accounts/accounts.sqlite` | Persistent accounts and saved settings |
| `BLOB_DIR` | `/tmp/evakage-blobs` | Temporary encrypted relay buffer |

Keep accounts in their separate named volume. **Do not mount a persistent relay volume.**

When running from source, accounts are disabled unless you set `ACCOUNTS_DB`. Local relay data defaults to an `evakage-blobs` directory inside your operating system's temporary directory.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.