Skip to main content

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.

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

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 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. guardrails — Split into input (validated before invocation) and output (validated after). Uses Guardrails AI Hub 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. mcp_servers — Model Context Protocol servers that provide tools to your agent. Supports stdio, sse, streamable_http, and websocket transports. See MCP Servers. 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. 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.

​
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: 
idun agent serve --source file --path config.yaml

​
Environment variables

VariablePurpose
IDUN_CONFIG_PATHPath to config.yaml. Used by idun setup and idun init on first boot.
IDUN_TELEMETRY_ENABLEDSet to false to disable anonymous usage telemetry
IDUN_DEPLOYMENT_TYPETag events with cloud, self-hosted, or dev
IDUN_TELEMETRY_IDENTIFY_USERSSet to false to keep all browser events anonymous (no email-level identify)
IDUN_TELEMETRY_SESSION_REPLAYSet 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. For the complete list of standalone environment variables, see the CLI reference.
Last modified on May 22, 2026