Skip to main content
The standalone runtime is the recommended way to ship an Idun agent (chat UI, admin panel, traces viewer, hot reload, SSO, all in one process). When you already have a FastAPI service and just want the engine’s agent routes inside it, or when you want to boot the engine from Python without idun init, drop down to the SDK below.

Public API

idun_agent_engine exports its surface from the package root:
Source: libs/idun_agent_engine/src/idun_agent_engine/__init__.py.

Boot the engine from Python

The lowest-friction path is run_server_from_config. It loads config.yaml, builds the FastAPI app, and starts uvicorn in one call. The port comes from server.api.port in the config unless you override.
run_server_from_config accepts every kwarg run_server does (host, port, reload, log_level, workers). It blocks until uvicorn exits. For programmatic configuration, swap the YAML for a ConfigBuilder:
ConfigBuilder validates each section as it is added; .build() returns a fully validated EngineConfig you can also pass directly to create_app(engine_config=...).

Embed the engine into an existing FastAPI app

create_app(...) returns a regular FastAPI instance with the agent routers (/agent/run, /agent/stream, /agent/sessions, /agent/capabilities, the deprecated /agent/invoke) and the base routes (/health, /reload, /_engine/info, /openapi.json) already attached. Mount that into your existing app:
After mounting, POST /idun/agent/run hits the engine’s AG-UI streaming endpoint and GET /idun/health returns the engine’s health payload. Your own routes at /billing/* keep working. Three things to know when embedding:
  1. CORS. create_app adds wide-open CORS middleware to the engine’s app (allow_origins=["*"]). Mount it inside a parent that owns CORS for the rest of your surface, otherwise the engine’s permissive middleware applies to every embedded route.
  2. POST /reload. Pass reload_auth=... to create_app to gate it behind a FastAPI dependency. Without that, the route is unauthenticated. The standalone runtime injects its own reload_disabled callable here. Reference: Architecture / Reload auth.
  3. Lifespan. The engine ships its own lifespan context manager. When you mount it into a parent FastAPI app, FastAPI runs the mounted app’s lifespan automatically; you do not need to wire it manually.

Unconfigured boot

create_app() with no config (no config_path, no config_dict, no engine_config, no ./config.yaml in cwd) boots in unconfigured mode: every route is registered, but /agent/* returns 503 agent_not_ready until you supply a config. Embedders use this to start the process before they know which agent to serve, then call the engine’s reload pipeline once the config is ready. The standalone runtime uses this shape during the first-run wizard.

Run the server explicitly

When you have an engine_config in hand and want full control over the uvicorn lifecycle, build the app first and call run_server separately:
run_server is a thin wrapper around uvicorn.run with sensible defaults. Skip it entirely if you already run uvicorn (or Gunicorn, or Hypercorn) yourself; create_app returns a FastAPI you can hand to any ASGI server.

Source pointers

Next steps

Programmatic chat: /agent/run contract

The HTTP shape the chat UI uses, including AG-UI request body and SSE events.

Custom adapter

Implement BaseAgent for a framework Idun does not bundle yet.

Standalone admin and reload

How the standalone runtime hot-reloads on top of these same primitives.
Last modified on May 26, 2026