> ## 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.

# Configuring Platform Settings on a Self-Hosted Egma

> Configure the LLM persona, speech providers, VAD, phone trunk, and judge defaults for your self-hosted Egma instance using the CLI or the API.

A started Egma instance is not yet a configured one. Before it can conduct simulations, it needs to know what the persona thinks with, how it speaks and hears, and — for phone simulations — how calls reach the telephone network. The platform reports `setup: setup_required` and names each missing setting until you supply it. Once you do, those settings live in the platform's own database, sealed with `EGMA_ENCRYPTION_KEY`, so they survive a restart, an upgrade, and a move to another machine. Every simulator is handed the current settings on the work order it claims — a second simulator on another host needs nothing copied to it.

You can configure the platform in two ways: interactively with `egma self-host setup`, or programmatically via the `PATCH /api/platform/settings` endpoint.

***

## Interactive setup

Run the setup command in the same directory as your `.env` file, logged in as the instance owner:

```bash theme={null}
npx @egma/cli login --url http://localhost:3101   # once, as the owner
npx @egma/cli self-host setup
```

The command reads the platform for what is already configured, then asks only for what is missing — in a fixed order: model provider first, then speech providers, then the phone trunk. A setting the platform already holds is never asked for again. Run it after adding one more provider key and it asks a single question.

Use `--plan` to preview what it would ask without writing anything:

```bash theme={null}
npx @egma/cli self-host setup --plan
```

Use `--apply --yes --json` for unattended configuration, with answers supplied via the environment variables listed in `.env.example`:

```bash theme={null}
npx @egma/cli self-host setup --apply --yes --json
```

<Note>
  `egma self-host setup` does **not** ask for the default judge. To set a deployment-wide default judge, add `EGMA_JUDGE_PROVIDER`, `EGMA_JUDGE_MODEL`, and `EGMA_JUDGE_API_KEY` to your `.env` file — see [Configuration keys — Default judge](#default-judge) below for details.
</Note>

***

## API-level setup

Update settings programmatically with a `PATCH` request. Supply only the keys you want to change — omitted keys are left exactly as they are:

```bash theme={null}
curl -sX PATCH http://localhost:3101/api/platform/settings \
  -H "Authorization: Bearer egma_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "personaModelProvider": "openai",
    "personaModel": "gpt-4o",
    "personaModelApiKey": "sk-..."
  }'
```

The platform seals every API key and credential before storing it. Keys are never returned in full — responses include only the last four characters of each secret, prefixed with `****`, so you can confirm which key is stored without exposing it.

***

## Configuration keys

The table below covers every setting the platform stores. The **env var** column shows the `.env.example` variable that seeds a setting on first boot (the API writes it into the store on startup if the store does not already hold it, and never overwrites an existing value).

### Persona model

The model the simulator's persona uses to generate responses during a simulation.

| Setting key            | Env var                       | Description                                                                        |
| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| `personaModelProvider` | `EGMA_PERSONA_MODEL_PROVIDER` | LLM provider — for example, `openai`.                                              |
| `personaModel`         | `EGMA_PERSONA_MODEL`          | Model name — for example, `gpt-4o`.                                                |
| `personaModelApiKey`   | `EGMA_PERSONA_MODEL_API_KEY`  | API key for the provider. Sealed at rest; only the last 4 characters are returned. |

### Speech-to-text (STT)

What the persona uses to transcribe the agent's audio during voice simulations.

| Setting key          | Env var                     | Description                                                                            |
| -------------------- | --------------------------- | -------------------------------------------------------------------------------------- |
| `personaSttProvider` | `EGMA_PERSONA_STT_PROVIDER` | STT provider — for example, `deepgram`.                                                |
| `personaSttApiKey`   | `EGMA_PERSONA_STT_API_KEY`  | API key for the STT provider. Sealed at rest; only the last 4 characters are returned. |

### Text-to-speech (TTS)

What the persona uses to speak during voice simulations.

| Setting key          | Env var                     | Description                                                                            |
| -------------------- | --------------------------- | -------------------------------------------------------------------------------------- |
| `personaTtsProvider` | `EGMA_PERSONA_TTS_PROVIDER` | TTS provider — for example, `elevenlabs`.                                              |
| `personaTtsApiKey`   | `EGMA_PERSONA_TTS_API_KEY`  | API key for the TTS provider. Sealed at rest; only the last 4 characters are returned. |
| `personaTtsModel`    | `EGMA_PERSONA_TTS_MODEL`    | TTS model name, when the provider offers a choice.                                     |
| `personaTtsVoice`    | `EGMA_PERSONA_TTS_VOICE`    | Voice identifier for the TTS provider.                                                 |

### Voice activity detection (VAD)

What tells the persona when the agent has started and stopped speaking.

| Setting key          | Env var                     | Description                                                                       |
| -------------------- | --------------------------- | --------------------------------------------------------------------------------- |
| `personaVadProvider` | `EGMA_PERSONA_VAD_PROVIDER` | VAD provider. `silero` is bundled and keyless — recommended for most deployments. |

### Default judge

The judge that a new project receives when it has not configured one of its own. Set all three or none — a partial configuration causes the API to refuse startup. These are set via `.env` rather than through `egma self-host setup`, because a judge belongs to the project that chose it rather than to the deployment.

| Setting key     | Env var               | Description                                                                                                                                                                                                |
| --------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `judgeProvider` | `EGMA_JUDGE_PROVIDER` | LLM provider for judging conversations — for example, `openai`.                                                                                                                                            |
| `judgeModel`    | `EGMA_JUDGE_MODEL`    | Model name — for example, `gpt-4o`.                                                                                                                                                                        |
| `judgeApiKey`   | `EGMA_JUDGE_API_KEY`  | API key for the judge provider. Sealed at rest; only the last 4 characters are returned. Written into each new project's configuration at boot; never overwrites a judge a project has already configured. |

<Note>
  These are not set interactively by `egma self-host setup`. Add them to your `.env` file — see [Environment Variables](/configuration/environment-variables) for the generation commands.
</Note>

### Media backend and phone trunk

Required for phone simulations. `egma self-host setup` configures Twilio automatically, including creating the SIP trunk and credential list; use these variables for other carriers or to supply values without interactive prompts.

| Setting key          | Env var                     | Description                                                                                                                       |
| -------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `mediaBackend`       | `EGMA_MEDIA_BACKEND`        | The bridge that places calls — for example, `livekit`.                                                                            |
| `phoneTrunkAddress`  | `EGMA_PHONE_TRUNK_ADDRESS`  | SIP trunk address, as provided by your carrier.                                                                                   |
| `phoneSourceNumber`  | `EGMA_PHONE_SOURCE_NUMBER`  | The phone number calls originate from, in E.164 format — for example, `+15551234567`. Must already exist on your carrier account. |
| `phoneTrunkUsername` | `EGMA_PHONE_TRUNK_USERNAME` | SIP credential username for trunk authentication.                                                                                 |
| `phoneTrunkPassword` | `EGMA_PHONE_TRUNK_PASSWORD` | SIP credential password. Sealed at rest; only the last 4 characters are returned.                                                 |

<Tip>
  For Twilio, run `egma self-host setup` and press Enter past the model and speech questions to reach the phone configuration. The command reads your Twilio account, shows a plan of what it will create, and writes the trunk address, source number, and SIP credential directly into the platform's store on approval. The Twilio Auth Token is used only during that command and is never stored.
</Tip>

***

## How secrets are stored

Every API key, password, and credential you store through platform settings is sealed with the deployment's `EGMA_ENCRYPTION_KEY` before it is written to the database. Retrieval responses return only the last four characters of each secret — for example, `****a1b2` — so you can identify which key is stored without exposing it. The plaintext is never returned through the API after it is written.

<Warning>
  Back up `EGMA_ENCRYPTION_KEY` alongside your database. The stored credentials and settings are unrecoverable without it — a database backup without the key is half a backup.
</Warning>

***

## Checking setup status

Read the current setup status at any time:

```bash theme={null}
curl -s http://localhost:3101/api/health | jq .setup
```

The response names each missing setting individually. A fully configured platform reports `setup_complete`. A platform with no phone trunk configured reports phone readiness separately — text simulations work without a carrier.