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.

The admin panel at /admin/ is the runtime source of truth for an Idun standalone deployment. After first boot, every change a user makes in the UI is staged as a DB write, validated, and applied to the running engine without restarting the process. This page explains that pipeline.

​
What lives at /admin/

Each section maps to a row in the standalone DB. Saving from the UI hits /admin/api/v1/* and triggers the reload pipeline below.
  • Agent: framework, model, system prompt, graph definition, ADK app name, session/memory services.
  • MCP servers: stdio, HTTP, SSE, WebSocket transports and the tools each advertises.
  • Managed prompts: versioned prompt rows your agent code reads via get_prompt(...).
  • Guardrails: input and output guards from the Guardrails AI hub, validators, or custom validators.
  • Observability: Langfuse, LangSmith, Phoenix, GCP Trace.
  • Integrations: Slack, Teams, and other messaging surfaces that route through the agent.
  • SSO and admin users: when IDUN_ADMIN_AUTH_MODE=password, manage the local admin roster and SSO providers.
  • Theme: branding for the embedded chat UI.

​
Save: the three-round pipeline

When a user clicks Save in the admin panel, the standalone runs through three rounds. The pipeline lives in services/reload.py and is guarded by a single in-process asyncio.Lock so concurrent saves serialize cleanly.
1

Round 1: request validation

FastAPI validates the request body against the admin REST schema. A bad shape returns 422 before the handler runs.
2

Round 2: assembly and cross-field validation

The staged DB mutation is assembled into a full EngineConfig via assemble_engine_config(session), then re-validated for cross-field rules (e.g. LangGraph requires a checkpointer at request time). On failure the DB is rolled back and the API returns 422 with field-level errors.
3

Round 3: engine reload

The new EngineConfig is applied to the live engine via the engine’s own lifecycle hooks: cleanup_agent(app) tears down the current agent, then configure_app(app, config) rebuilds it on the same FastAPI instance. No process restart, no port flap.The active prompts snapshot is published just before this step so user code calling get_prompt(...) at module import time during exec_module sees the new value.On failure: the DB mutation is rolled back, the prompts snapshot reverts to the prior value, the reload outcome is recorded as RELOAD_FAILED in runtime_state, and the API returns 500 with code: reload_failed.
The reload callable itself lives in services/engine_reload.py:build_engine_reload_callable. It also catches the case where a new save introduces a guardrail that fails to install (typically a hub:// 401 or a missing transitive dep) and surfaces that as a round-three failure rather than letting configure_app return success with a silently inactive guardrail.

​
When a process restart IS required

Most config changes hot-reload. Two fields make up the “structural slice” that cannot be hot-swapped:
  • agent.type (framework: LangGraph, ADK, Deep Agents)
  • agent.config.graph_definition (LangGraph entry point path)
A save that changes either is committed to the DB but NOT applied to the running engine. The API returns status: restart_required, and the admin UI shows a banner reminding the operator to restart. The structural slice is defined in services/reload.py:_structural_slice. Every other field hot-reloads in place: agent name, description, prompts, MCP servers, guardrails, observability providers, messaging integrations, theme.

​
Failure isolation

Pre-existing failures from earlier saves do not block new ones. The reload callable tracks the set of currently-failing guardrails and only treats a new save as failed if it INTRODUCES a regression. This keeps the admin usable even when a previously-installed guardrail dep has gone stale.

​
Source pointers

ConcernFile
Top-level pipelinelibs/idun_agent_standalone/services/reload.py
Engine reload callablelibs/idun_agent_standalone/services/engine_reload.py
App composition and runtime gatelibs/idun_agent_standalone/src/idun_agent_standalone/app.py
Engine lifecycle hookslibs/idun_agent_engine/src/idun_agent_engine/server/lifespan.py

​
Next steps

CLI reference

Every idun command, what it does, and its flags.

Cloud Run deployment

Deploy the standalone to Google Cloud Run.

Customizing the UI

Theme the chat UI and pick a layout variant.
Last modified on May 26, 2026