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

# Configuration

> Engine configuration reference for server settings, agent framework, observability, guardrails, memory, MCP, SSO, and integrations.

A single `EngineConfig` controls every aspect of your agent service. Define it as a YAML file (the bootstrap path) or edit it through the standalone admin panel at `/admin/`. The structure is identical in both cases; the admin panel is just a UI over the same fields.

## Complete config example

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
server:
  api:
    port: 8001

agent:
  type: "LANGGRAPH"
  config:
    name: "Support Agent"
    graph_definition: "./agent.py:graph"
    checkpointer:
      type: "sqlite"
      db_url: "sqlite:///checkpoints.db"

observability:
  - provider: "LANGFUSE"
    enabled: true
    config:
      host: "https://cloud.langfuse.com"
      public_key: "${LANGFUSE_PUBLIC_KEY}"
      secret_key: "${LANGFUSE_SECRET_KEY}"

guardrails:
  input:
    - config_id: "DETECT_PII"
      on_fail: "reject"
      reject_message: "Request contains personal information."
  output:
    - config_id: "TOXIC_LANGUAGE"
      on_fail: "reject"

mcp_servers:
  - name: "time"
    transport: "stdio"
    command: "docker"
    args: ["run", "-i", "--rm", "mcp/time"]

prompts:
  - prompt_id: "system-prompt"
    version: 1
    content: "You are a support agent for {{ company_name }}."
    tags: ["latest"]

sso:
  enabled: true
  issuer: "https://accounts.google.com"
  client_id: "123456789.apps.googleusercontent.com"
  allowed_domains: ["yourcompany.com"]

integrations:
  - provider: "WHATSAPP"
    enabled: true
    config:
      access_token: "${WHATSAPP_ACCESS_TOKEN}"
      phone_number_id: "${WHATSAPP_PHONE_ID}"
      verify_token: "${WHATSAPP_VERIFY_TOKEN}"
```

Values support `${ENV_VAR}` syntax for referencing environment variables at load time.

## Config sections

**`server`** -- HTTP server binding. Exposes `api.port` (default: `8000`). CORS allows all origins. The engine adds `Access-Control-Allow-Private-Network: true` so hosted UIs can reach local agents.

**`agent`** -- Framework type and framework-specific settings. The `config` fields change based on the `type` value. Supported types: `LANGGRAPH`, `ADK`. See the [frameworks overview](/frameworks/overview) for per-framework config details.

For LangGraph, provide a `StateGraph` via `graph_definition` (`path/to/file.py:variable_name`). The engine compiles it with the configured checkpointer. A `CompiledStateGraph` is also accepted (the engine extracts `.builder` and recompiles).

**`observability`** -- A list of providers, each with `provider`, `enabled`, and `config`. Multiple providers can be active simultaneously. Supported: `LANGFUSE`, `PHOENIX`, `GCP_TRACE`, `GCP_LOGGING`, `LANGSMITH`. See [observability guides](/observability/overview).

**`guardrails`** -- Split into `input` (validated before invocation) and `output` (validated after). Uses [Guardrails AI Hub](https://hub.guardrailsai.com/) guards, downloaded and run locally. Available guards: `BAN_LIST`, `DETECT_PII`, `NSFW_TEXT`, `COMPETITION_CHECK`, `BIAS_CHECK`, `CORRECT_LANGUAGE`, `GIBBERISH_TEXT`, `TOXIC_LANGUAGE`, `RESTRICT_TO_TOPIC`. See [guardrails reference](/guardrails/reference).

**`mcp_servers`** -- Model Context Protocol servers that provide tools to your agent. Supports `stdio`, `sse`, `streamable_http`, and `websocket` transports. See [MCP Servers](/mcp-servers/overview).

**`prompts`** -- Versioned prompt templates with Jinja2 variable support (`{{ variable }}`). Each entry has `prompt_id`, `version`, `content`, and `tags`.

**`sso`** -- OIDC JWT validation on agent endpoints. When enabled, requests to `/agent/run` must include a valid token. Supports `allowed_domains` and `allowed_emails` filtering. See [SSO](/auth/sso).

**`integrations`** -- Messaging platform connections. Each integration adds webhook endpoints to the engine. Supported: `WHATSAPP`, `DISCORD`.

**`checkpointer`** (inside `agent.config` for LangGraph) -- Conversation memory. Types: `memory` (in-process), `sqlite`, `postgres`. For ADK, use `session_service` and `memory_service` instead. See [memory guides](/memory/overview).

## Config sources

The standalone runtime has two ways to land config in the DB:

* **YAML bootstrap.** On first boot, if the DB is empty, the file at `IDUN_CONFIG_PATH` (default `./config.yaml`) seeds it. After that, the DB is the source of truth.
* **Admin panel.** Open `/admin/` and edit any section. Each save flows through the reload pipeline and re-instantiates the engine atomically; a bad save rolls back without disturbing the running agent.

For the engine-only mode (no DB, no admin), serve directly from a YAML file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
idun agent serve --source file --path config.yaml
```

## Environment variables

| Variable                        | Purpose                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `IDUN_CONFIG_PATH`              | Path to config.yaml. Used by `idun setup` and `idun init` on first boot.        |
| `IDUN_TELEMETRY_ENABLED`        | Set to `false` to disable anonymous usage telemetry                             |
| `IDUN_DEPLOYMENT_TYPE`          | Tag events with `cloud`, `self-hosted`, or `dev`                                |
| `IDUN_TELEMETRY_IDENTIFY_USERS` | Set to `false` to keep all browser events anonymous (no email-level `identify`) |
| `IDUN_TELEMETRY_SESSION_REPLAY` | Set to `false` to ship browser analytics without recording sessions             |

The engine resolves `${VAR_NAME}` references in YAML values at config load time, so you can keep secrets out of your config files.

For the full list of browser events captured and PostHog masking conventions, see [Telemetry events](/observability/telemetry-events). For the complete list of standalone environment variables, see the [CLI reference](/cli/overview#environment-variables).