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.

idun is the single console script installed by pip install idun-agent-engine. It covers the full lifecycle: scaffold a project, serve the standalone, run engine-only, hash a password, pre-stage migrations. All commands accept --help.

​
Quick reference

VerbMigrates schemaSeeds from config.yamlServes uvicornNotes
idun initYesYes (only if rows missing)YesFirst-run bootstrap. Opens the browser to the wizard if no agent row exists yet. Idempotent.
idun setupYesYes (only if rows missing)NoPre-stage the DB during a deploy, or re-run the seeder after wiping rows.
idun serveNoNoYesSteady-state startup. DB is the source of truth; config.yaml is not consulted.
idun agent serveNoNoYesEngine-only mode. No DB, no admin surface, just the engine routes.
idun hash-passwordNoNoNoPrint a bcrypt hash for IDUN_ADMIN_PASSWORD_HASH.
The seeder writes a row only if the corresponding table is empty. To re-seed after config.yaml changes, clear the row first (or delete idun_standalone.db for a full reset) and re-run idun setup. See Troubleshooting for the full re-seed recipe.

​
Common flows

mkdir my-agent && cd my-agent
idun init           # runs migrations, opens the onboarding wizard in your browser

​
Commands

​
idun init

Initialize Idun in the current folder and launch chat + admin in one step. Runs migrations, seeds from config.yaml if present, opens the browser, and boots the standalone server. Idempotent, so re-running on an already-initialized folder just re-launches. 
idun init
FlagDefaultDescription
--port <int>IDUN_PORT env, then 8000Bind port.
--no-browseroffSkip the automatic browser open. Useful for headless / Cloud Run.

​
idun serve

Run the standalone server. The DB is the source of truth in steady state; on first boot, if the DB is empty and IDUN_CONFIG_PATH points to a YAML file, the file seeds the DB. 
idun serve
No flags. All configuration is read from environment variables (see Environment variables).

​
idun setup

Create the DB schema and seed it from YAML if the DB is empty. Called automatically by serve and init, but operators can run it directly to pre-stage migrations during a deploy. 
idun setup
FlagDefaultDescription
--config <path>IDUN_CONFIG_PATH env, then ./config.yamlBootstrap YAML file.

​
idun agent serve

Run an engine-only server with no DB and no admin surface. Useful when you have your own admin stack and only want the runtime layer. 
idun agent serve --source file --path ./config.yaml
FlagDefaultDescription
--sourcerequiredMust be file (load config from a local YAML).
--path <path>required when --source=filePath to the YAML.
--source manager is still present in idun agent serve --help as a leftover from the pre-0.6.0 manager-tier deployment model. It is deprecated and unsupported: the manager service no longer ships with the platform. Use --source file only.

​
idun hash-password

Print a bcrypt hash suitable for IDUN_ADMIN_PASSWORD_HASH. Used once at deploy time when setting up password auth mode. 
idun hash-password
FlagDefaultDescription
--password <plaintext>prompted (with confirmation)Plaintext password to hash. Prompted if omitted.

​
Environment variables

serve (and the server side of init) reads every setting from the environment. The defaults below match what the standalone uses out of the box.

​
Server binding

VariableDefaultDescription
IDUN_HOST127.0.0.1Bind address. Set 0.0.0.0 for containers (requires IDUN_ADMIN_AUTH_MODE=password or IDUN_ALLOW_OPEN_ADMIN=1).
IDUN_PORT8000Bind port.
IDUN_UI_DIRbundled static exportOverride the chat/admin UI directory.

​
Database

VariableDefaultDescription
DATABASE_URLsqlite+aiosqlite:///./idun_standalone.dbSQLAlchemy URL. Use postgresql+asyncpg://… for Postgres.
IDUN_CONFIG_PATH./config.yamlBootstrap YAML file used by setup / init on an empty DB.

​
Admin auth

VariableDefaultDescription
IDUN_ADMIN_AUTH_MODEnoneAdmin gate. none for laptop dev; password for containers.
IDUN_ADMIN_PASSWORD_HASHemptyBcrypt admin hash. Required on the first boot under IDUN_ADMIN_AUTH_MODE=password to seed the singleton admin row; subsequent boots ignore this variable and read the hash from the DB. Generate with idun hash-password.
IDUN_SESSION_SECRETemptyAt least 32 characters. Signs the idun_session cookie. Required when IDUN_ADMIN_AUTH_MODE=password; startup fails fast if shorter.
IDUN_SESSION_TTL_HOURS24Session cookie lifetime in hours (range 1..720).
IDUN_ALLOW_OPEN_ADMINfalseOpt-in flag that lets auth_mode=none bind 0.0.0.0 / ::. Containers and trusted networks only.

​
Trace store

VariableDefaultDescription
IDUN_TRACE_RETENTION_DAYS14Days of trace events the daily retention task keeps before dropping.
IDUN_TRACES_INPUT_VALUE_MAX_BYTES65536Per-attribute byte cap before the exporter truncates trace input/output values.
IDUN_PRICES_REFRESHfalseWhen true, fetch the LiteLLM model-prices snapshot at boot (5 s timeout, snapshot fallback).

​
Telemetry

VariableDefaultDescription
IDUN_TELEMETRY_ENABLEDtrueSet to false to disable anonymous usage telemetry.
IDUN_DEPLOYMENT_TYPEself-hostedTag events with cloud, self-hosted, or dev.
IDUN_TELEMETRY_IDENTIFY_USERStrueSet to false to keep all browser events anonymous (no email-level identify).
IDUN_TELEMETRY_SESSION_REPLAYtrueSet to false to ship browser analytics without recording sessions.

​
Verifying a running agent

Once idun serve is up, open the bundled chat UI at http://localhost:8000/. You land on the welcome screen.
Chat UI welcome state
Send a message. The chat surface streams the AG-UI response in real time and renders tool calls inline.
Chat UI showing a hello/Hey-what's-up exchange
Open /admin/traces/ to inspect the run after it completes. If you need to hit /agent/run directly from a script or external client, see Programmatic chat for the request shape and SSE event stream.

​
API documentation

The OpenAPI schema is auto-published at /docs on the running standalone. Open http://localhost:8000/docs in your browser: 
# macOS
open http://localhost:8000/docs

# Linux
xdg-open http://localhost:8000/docs

# Windows (cmd)
start http://localhost:8000/docs

​
Next steps

Programmatic chat

Hit /agent/run directly with the request shape and SSE event stream.

Customize the chat UI

Theme, layout, and full UI replacement.

Deploy to Cloud Run

Run idun serve on Google Cloud Run with a managed container.
Last modified on May 22, 2026