FAQ - Idun Engine

What agent frameworks are supported?

Idun Engine supports two agent frameworks:

LangGraph (primary): Full support for graph definitions, checkpointing, memory, and streaming
Google ADK (Agent Development Kit): Support for agent definitions, session services, and memory services

The framework is specified in the agent.type config field. Each framework has its own adapter in the engine that handles initialization, execution, and streaming. See Frameworks for details.

How does authentication work?

There are two distinct auth surfaces.Standalone admin panel. Two modes via IDUN_ADMIN_AUTH_MODE:

none: open admin (laptop default).
password: bcrypt password + signed session cookie with sliding renewal.

Use idun hash-password to generate the bcrypt hash, set it as IDUN_ADMIN_PASSWORD_HASH on first boot, and set IDUN_SESSION_SECRET (min 32 chars) when running in password mode.Agent runtime routes. The engine can enforce OIDC JWT validation on /agent/* via a per-agent SSO config. Clients must present a valid bearer token; tokens are not stored. Some operational endpoints stay outside per-agent auth, so deploy inside a trusted network boundary and follow the hardening guidance.See Authentication for setup instructions.

Does Idun require a database?

The default path (standalone) uses a database. The engine-only mode does not.Standalone (default). The standalone holds admin state and AG-UI trace events in a database. SQLite by default (a file on disk). Postgres optional via DATABASE_URL. Without a DB the standalone has nowhere to persist admin edits, traces, or session cookies.Engine-only. No database required. The engine reads its YAML config at boot and serves the agent. Conversation state is whatever you configure for the LangGraph checkpointer (in-memory, SQLite file, or Postgres) or the ADK session service. With in_memory, nothing is persisted.

Where is data stored?

Agent code: Lives in your repository. The engine wraps your code at runtime; it does not copy or store it.
Standalone: Admin state (agent config, prompts, guardrails, MCP servers, observability, integrations, theme) and trace events live in the local database (SQLite by default, Postgres optional).
Engine-only: Configuration comes from a YAML file. Conversation state goes to whichever checkpointer or session service you configure.

Can I run without the admin DB?

Yes. The engine ships an engine-only mode that skips the admin REST surface and the local DB entirely:

pip install idun-agent-engine
idun agent serve --source file --path config.yaml

No DB, no chat UI, no admin REST. Good for CI/CD pipelines or when you have your own admin stack and only need the runtime layer. The full standalone product is what idun serve (or idun init) gives you, and it does require a DB.

How do guardrails work?

Guardrails validate agent inputs and outputs against configurable rules. You define guardrails as input guards, output guards, or both:

Input guardrails check user messages before they reach the agent (e.g., jailbreak detection, PII detection)
Output guardrails check agent responses before they are returned to the user (e.g., toxic language filtering, topic restriction)

Each guardrail has a type, a reject message, and type-specific configuration (threshold, word list, topic list). The engine evaluates guardrails in order and returns the reject message if a guard triggers.The platform supports 15 guardrail types, including BAN_LIST, DETECT_PII, TOXIC_LANGUAGE, DETECT_JAILBREAK, PROMPT_INJECTION, RESTRICT_TO_TOPIC, MODEL_ARMOR (Google Cloud), and CUSTOM_LLM. See the guardrails reference for the full list.

Engine-only vs standalone, what's the difference?

	Standalone (default)	Engine-only
Role	Single-process product: engine plus chat UI, admin REST, traces	Runtime SDK that wraps your agent code into a production API
Run command	`idun serve` (or `idun init` first time)	`idun agent serve --source file --path config.yaml`
Requires	Python 3.12+, your agent code, a local file for SQLite	Python 3.12+, your agent code
Has a UI?	Yes (chat, admin, traces, bundled)	No
Has a DB?	Yes (SQLite by default; Postgres optional)	No
Config source	DB-backed (seeded from YAML on first boot)	YAML file
Auth	Admin: `none` or `password`. Agent routes: per-agent OIDC	Per-agent OIDC for `/agent/*`; rest open

Both modes ship in the same idun-agent-engine wheel. Pick by which command you run. See the glossary for the package layout.

Is it free and open source?

Yes. Idun Engine is open source and available on GitHub under the GNU General Public License v3.0 (GPLv3). The engine SDK (idun-agent-engine) and schema library (idun-agent-schema) are published to PyPI.

Does GPLv3 apply to my agent code?

The short answer: your agent code is generally treated as a separate work, not a derivative of Idun. The longer answer depends on how the parts interact. This section is informational, not legal advice; review the LICENSE and the FSF’s GPL FAQ before redistributing.

Your agent's graph_definition
MCP servers and external tools
LLM-generated code

The engine loads your LangGraph or ADK agent from agent.config.graph_definition and runs it in the same Python process. The FSF considers in-process Python imports across a clean API boundary to be a closer relationship than mere aggregation, so a strictly conservative reading would treat your agent code as a derivative work subject to GPL.In practice, most teams treat their agent code as a separate work because:

The interaction is through a documented public extension point (BaseAgent, schema config fields), not internal engine APIs.
Your agent code can be loaded into other runtimes without modification.
You ship your agent as code that the user combines with the engine, not as a bundled binary.

The boundary is not crystal-clear. If you plan to redistribute your agent code bundled with idun-agent-engine (a single wheel, container image, or installer) and your agent code is not GPL-compatible, get legal advice before shipping.Running the engine privately (internally, on your own infrastructure, with your own users) imposes no GPL distribution obligations.

Code generated by an LLM does not inherit a license from the LLM provider. The license applicable to LLM-generated code is whatever your provider’s terms of service say (most major providers grant you rights to the output, subject to acceptable-use policies).If you paste LLM-generated code into your graph_definition, the GPL question is the same as for any other agent code (see the first tab). The LLM provenance does not change the analysis.

If you need a non-GPL license for commercial redistribution, contact us via Discord to discuss options.

How do I report a bug or request a feature?

Bugs and feature requests: GitHub Issues
Questions and discussions: Discord

How does observability work?

The engine uses OpenTelemetry-based auto-instrumentation to capture traces, logs, and metrics from your agents. You configure an observability provider (Langfuse, Arize Phoenix, LangSmith, GCP Trace, or GCP Logging) and the engine instruments the agent runtime automatically.Observability configurations are saved at the workspace level and can be reused across multiple agents. See Observability for provider setup.

Can I use multiple MCP servers with one agent?

Yes. You can attach any number of MCP servers to a single agent. The engine discovers tools from all attached MCP servers at startup and makes them available to the agent. Each server can use a different transport type (stdio, SSE, streamable HTTP, WebSocket). See MCP Servers for details.

Documentation Index