> ## Documentation Index > Fetch the complete documentation index at: https://docs.egma.ai/llms.txt > Use this file to discover all available pages before exploring further. # Environment Variables Reference for Egma Self-Hosting > Complete reference for every environment variable Egma reads on startup — required secrets, optional defaults, and the commands that generate safe values. Copy `.env.example` to `.env` before you start the platform. Most variables have working defaults that are safe to leave alone. Ten do not — the deployment refuses to start if any one of them is absent, printing the name of the missing variable rather than guessing at a value. Those ten are your deployment's own secrets and its own address: a default for any of them would be a value every reader of this repository already holds. The sections below separate what you must supply from what you can safely leave at its default. *** ## Required variables Set all seven of the following before running `egma self-host up`. The remaining three (`EGMA_BASE_URL`, `EGMA_LIVEKIT_API_KEY`, `EGMA_LIVEKIT_API_SECRET`) are set automatically by `egma self-host up` and do not need to be set by hand unless you are driving `docker compose` directly. 32 random bytes encoded as 64 hex characters. Seals every provider credential and platform setting stored in the database. Back this up alongside the database — the sealed values are unrecoverable without it. ```bash theme={null} openssl rand -hex 32 ``` A random base64 string that signs session cookies. The API refuses to start without one. ```bash theme={null} openssl rand -base64 32 ``` The bearer token the simulator presents when claiming simulation work from the API. The API checks it on every claim request — the responses carry live provider credentials. Must start with the prefix `egma_st_` so leak-scanning tools can recognise it. ```bash theme={null} echo "egma_st_$(openssl rand -hex 32)" ``` The MinIO root credential username. You choose this value — minimum 8 characters. This credential has full write, delete, and list access to the object store, so treat it as a secret and **change `EGMA_S3_SECRET_ACCESS_KEY` before opening the store port to a network**. The MinIO root credential password. You choose this value — minimum 8 characters. Paired with `EGMA_S3_ACCESS_KEY_ID` above. **The read credentials below are created by the deployment on first start.** The deployment's `minio-init` job creates a restricted user that can fetch one object at a time and cannot write, delete, or list. Copy both values from your startup logs the first time you run `egma self-host up`, then paste them here and restart. The MinIO read-only credential username. Created by the deployment on first start — copy from startup logs. The MinIO read-only credential password. Created by the deployment on first start — copy from startup logs. ### Variables set automatically by `egma self-host up` If you drive `docker compose` directly without the CLI, supply these three yourself. If you use `egma self-host up`, the CLI generates and writes them for you and they do not need to appear in `.env`. The full public URL of your instance — scheme, host, and port only. No path, query string, or trailing slash. Example: `http://localhost:3101`. Every agent repository that connects to this instance reads its identity from this value. If others reach your instance at `http://192.168.1.10:3101`, this must say exactly that — not `http://localhost:3101`. The API key used to authenticate the LiveKit media server, simulator, and SIP gateway with each other. Generated by `egma self-host up` and written to `.egma-platform/platform.env`. Do not choose this value manually. The API secret paired with `EGMA_LIVEKIT_API_KEY`. Generated alongside it by `egma self-host up`. *** ## Optional variables with defaults All variables in this section have working defaults. Override them only when the default conflicts with your environment — for example, if the default ports are already in use on the host. ### PostgreSQL The PostgreSQL role name used by the API. Password for `POSTGRES_USER`. Change this — and narrow or close the bind address — before exposing port 5433 to any network. The PostgreSQL database name. The port PostgreSQL publishes on the host. Published as 5433 (not 5432) to avoid colliding with a PostgreSQL instance already running on the machine. The address PostgreSQL binds to on the host. Loopback by default — this is a security decision, not an omission. The password above is printed in this repository; binding to `0.0.0.0` on a shared network hands every row in the database to whoever can route to the machine. Widen it only when something off this machine must reach the database, and change `POSTGRES_PASSWORD` at the same time. ### ClickHouse The ClickHouse user name. Holds every conversation trace your platform records. Password for `CLICKHOUSE_USER`. Same caution as `POSTGRES_PASSWORD` applies. The ClickHouse database name. The port ClickHouse publishes on the host. Published as 8124 (not 8123) to avoid collisions. The address ClickHouse binds to on the host. Loopback by default for the same reason as `POSTGRES_BIND`. ### Object storage (S3 / MinIO) The bucket recordings land in. Created on first start. Change this only if you are pointing Egma at a bucket you already own. The AWS region included in object-store request signatures. Leave empty for MinIO, which ignores regions entirely. Set to the real region (for example, `us-east-1`) when pointing Egma at Amazon S3 — the API refuses to start on an `amazonaws.com` endpoint without one rather than silently signing everything for the wrong region. Both the simulator (upload) and the API (playback-link signing) read this value, so set it once here and both halves use the same region. The port MinIO publishes on the host. Change this when port 9000 is already taken, and update `EGMA_BLOB_PUBLIC_URL` to match. The address MinIO binds to on the host. Loopback by default — what answers on this port is the store's admin surface. Set to `0.0.0.0` only when browsers that play recordings are not on this machine, and update `EGMA_BLOB_PUBLIC_URL` to the address those browsers use. The address **a browser** uses to reach the object store. This is not the address the API uses internally — confusing the two is the most common cause of `SignatureDoesNotMatch` errors on recording playback. Set this to the same host as `EGMA_BASE_URL`, on port 9000 (or whatever `EGMA_S3_PORT` is). If `EGMA_BASE_URL` uses `https:`, this must also use `https:` — browsers block mixed-content audio before the request is sent. ### API and web ports The port the API publishes on the host. The port the web application publishes on the host. This is the port that appears in `EGMA_BASE_URL` for a default deployment. ### Access and security When `true`, the first person to sign up claims the instance and becomes its admin. Open signup closes behind them — everyone after arrives by invitation. Set to `false` only for a multi-tenant deployment that intentionally holds many separate organizations. Whether to trust `x-forwarded-proto` and `x-forwarded-host` headers. Set to `true` only when a reverse proxy you control (nginx, Caddy, a load balancer) sits in front of the API — otherwise any client can claim any origin. The maximum number of authenticated requests one organization may make per minute. The budget belongs to the organization, not to a key, so rotating a key does not reset it. ### Email (optional) Email is entirely optional. Without it, invitation links are returned directly to the admin who created them, signup requires no verification, and password-reset links are written to the platform log. Before adding a second person to an instance that has no mail transport configured, be aware that password-reset links are written to the platform log. Anyone who can read that log — including a `docker compose logs` run by a colleague — can use a reset link to take over any account, including an admin account. Configure `EGMA_SMTP_URL` before granting log access to others. An SMTP connection URL. Setting this turns on email delivery for invitations, signup verification, and password resets all at once. ```bash theme={null} # Example EGMA_SMTP_URL=smtp://user:password@smtp.example.com:587 ``` The display name and address used in the `From` header. Optional — defaults to a bare address when omitted. ```bash theme={null} # Example EGMA_MAIL_FROM='Egma ' ``` *** ## Default judge These three variables seed the judge that a new project receives when it has not configured one of its own. Set all three or none — a partial judge configuration causes the API to refuse startup. The `egma self-host setup` command does not ask for these. A judge belongs to the project that chose it rather than to the deployment, so set them here in `.env` if you want every new project to have a default. The LLM provider to use for judging — for example, `openai`. The model name — for example, `gpt-4o`. The API key for the judge provider. Sealed with `EGMA_ENCRYPTION_KEY` and written into each new project's configuration at boot. Never overwrites a judge a project has already configured. *** ## Quick-start checklist Run these commands to generate all seven required secrets at once, then paste the output into your `.env`: ```bash theme={null} echo "EGMA_ENCRYPTION_KEY=$(openssl rand -hex 32)" echo "EGMA_AUTH_SECRET=$(openssl rand -base64 32)" echo "EGMA_SIMULATOR_SERVICE_TOKEN=egma_st_$(openssl rand -hex 32)" # Choose your own values for these — minimum 8 characters each: echo "EGMA_S3_ACCESS_KEY_ID=" echo "EGMA_S3_SECRET_ACCESS_KEY=" # After first start, copy these from startup logs: # EGMA_S3_READ_ACCESS_KEY_ID= # EGMA_S3_READ_SECRET_ACCESS_KEY= ``` Then start the platform: ```bash theme={null} npx @egma/cli self-host up ``` `egma self-host up` sets `EGMA_BASE_URL`, `EGMA_LIVEKIT_API_KEY`, and `EGMA_LIVEKIT_API_SECRET` automatically.