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 console script installed by the idun-agent-engine wheel (the standalone is bundled). All commands accept --help for inline documentation.

​
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 the table below).

​
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.

​
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.

​
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.

​
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.

​
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.

​
Next steps

Quickstart

Run your first agent in under 5 minutes.

Customize the chat UI

Theme, layout, and full UI replacement.

Deploy to Cloud Run

Run the standalone on Google Cloud Run with a managed container.
Last modified on May 20, 2026