CLI

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

Verb	Migrates schema	Seeds from `config.yaml`	Serves uvicorn	Notes
`idun init`	Yes	Yes (only if rows missing)	Yes	First-run bootstrap. Opens the browser to the wizard if no agent row exists yet. Idempotent.
`idun setup`	Yes	Yes (only if rows missing)	No	Pre-stage the DB during a deploy, or re-run the seeder after wiping rows.
`idun serve`	No	No	Yes	Steady-state startup. DB is the source of truth; `config.yaml` is not consulted.
`idun agent serve`	No	No	Yes	Engine-only mode. No DB, no admin surface, just the engine routes.
`idun hash-password`	No	No	No	Print 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

# IDUN_CONFIG_PATH points at config.yaml (default ./config.yaml)
idun setup     # one-time: migrations + seed the DB
idun serve     # bind 127.0.0.1:8000, admin at /admin/, traces at /admin/traces/

# No DB, no admin REST, no chat UI. Engine routes only.
idun agent serve --source file --path config.yaml

HASH=$(idun hash-password)
SECRET=$(openssl rand -hex 32)
IDUN_ADMIN_AUTH_MODE=password \
IDUN_ADMIN_PASSWORD_HASH="$HASH" \
IDUN_SESSION_SECRET="$SECRET" \
idun serve

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

Flag	Default	Description
`--port <int>`	`IDUN_PORT` env, then `8000`	Bind port.
`--no-browser`	off	Skip 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

Flag	Default	Description
`--config <path>`	`IDUN_CONFIG_PATH` env, then `./config.yaml`	Bootstrap 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

Flag	Default	Description
`--source`	required	Must be `file` (load config from a local YAML).
`--path <path>`	required when `--source=file`	Path 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

Flag	Default	Description
`--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

Variable	Default	Description
`IDUN_HOST`	`127.0.0.1`	Bind address. Set `0.0.0.0` for containers (requires `IDUN_ADMIN_AUTH_MODE=password` or `IDUN_ALLOW_OPEN_ADMIN=1`).
`IDUN_PORT`	`8000`	Bind port.
`IDUN_UI_DIR`	bundled static export	Override the chat/admin UI directory.

Database

Variable	Default	Description
`DATABASE_URL`	`sqlite+aiosqlite:///./idun_standalone.db`	SQLAlchemy URL. Use `postgresql+asyncpg://…` for Postgres.
`IDUN_CONFIG_PATH`	`./config.yaml`	Bootstrap YAML file used by `setup` / `init` on an empty DB.

Admin auth

Variable	Default	Description
`IDUN_ADMIN_AUTH_MODE`	`none`	Admin gate. `none` for laptop dev; `password` for containers.
`IDUN_ADMIN_PASSWORD_HASH`	empty	Bcrypt 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_SECRET`	empty	At least 32 characters. Signs the `idun_session` cookie. Required when `IDUN_ADMIN_AUTH_MODE=password`; startup fails fast if shorter.
`IDUN_SESSION_TTL_HOURS`	`24`	Session cookie lifetime in hours (range `1..720`).
`IDUN_ALLOW_OPEN_ADMIN`	`false`	Opt-in flag that lets `auth_mode=none` bind `0.0.0.0` / `::`. Containers and trusted networks only.

Trace store

Variable	Default	Description
`IDUN_TRACE_RETENTION_DAYS`	`14`	Days of trace events the daily retention task keeps before dropping.
`IDUN_TRACES_INPUT_VALUE_MAX_BYTES`	`65536`	Per-attribute byte cap before the exporter truncates trace input/output values.
`IDUN_PRICES_REFRESH`	`false`	When `true`, fetch the LiteLLM model-prices snapshot at boot (5 s timeout, snapshot fallback).

Telemetry

Variable	Default	Description
`IDUN_TELEMETRY_ENABLED`	`true`	Set to `false` to disable anonymous usage telemetry.
`IDUN_DEPLOYMENT_TYPE`	`self-hosted`	Tag events with `cloud`, `self-hosted`, or `dev`.
`IDUN_TELEMETRY_IDENTIFY_USERS`	`true`	Set to `false` to keep all browser events anonymous (no email-level `identify`).
`IDUN_TELEMETRY_SESSION_REPLAY`	`true`	Set 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.

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.

Get started

Guides

Standalone

Frameworks

Memory

Guardrails

Tools

Observability

Authentication

Integrations

Deploy

Reference

Advanced

Enterprise

Help

Quick reference

Common flows

Commands

`idun init`

`idun serve`

`idun setup`

`idun agent serve`

`idun hash-password`

Environment variables

Server binding

Database

Admin auth

Trace store

Telemetry

Verifying a running agent

API documentation

Next steps

Programmatic chat

Customize the chat UI

Deploy to Cloud Run

​Quick reference

​Common flows

​Commands

​idun init

​idun serve

​idun setup

​idun agent serve

​idun hash-password

​Environment variables

​Server binding

​Database

​Admin auth

​Trace store

​Telemetry

​Verifying a running agent

​API documentation

​Next steps

Programmatic chat

Customize the chat UI

Deploy to Cloud Run

Quick reference

Common flows

Commands

`idun init`

`idun serve`

`idun setup`

`idun agent serve`

`idun hash-password`

Environment variables

Server binding

Database

Admin auth

Trace store

Telemetry

Verifying a running agent

API documentation

Next steps