Configuring Platform Settings on a Self-Hosted Egma

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:

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:

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:

npx @egma/cli self-host setup --apply --yes --json

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 below for details.

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:

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.

These are not set interactively by egma self-host setup. Add them to your .env file — see Environment Variables for the generation commands.

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.

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.

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.

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.

Checking setup status

Read the current setup status at any time:

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.

Get Started

Core Concepts

Integrations

CLI Reference

Configuration

Configuring Platform Settings on a Self-Hosted Egma

Interactive setup

API-level setup

Configuration keys

Persona model

Speech-to-text (STT)

Text-to-speech (TTS)

Voice activity detection (VAD)

Default judge

Media backend and phone trunk

How secrets are stored

Checking setup status

​Interactive setup

​API-level setup

​Configuration keys

​Persona model

​Speech-to-text (STT)

​Text-to-speech (TTS)

​Voice activity detection (VAD)

​Default judge

​Media backend and phone trunk

​How secrets are stored

​Checking setup status

Interactive setup

API-level setup

Configuration keys

Persona model

Speech-to-text (STT)

Text-to-speech (TTS)

Voice activity detection (VAD)

Default judge

Media backend and phone trunk

How secrets are stored

Checking setup status