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 standalone is a single FastAPI process. Anywhere you can run a Python container, you can run Idun. The pages under this section cover the supported deployment surfaces.

​
Pick a target

Google Cloud Run

Managed container with HTTPS, autoscaling, and Cloud SQL Postgres. The shortest path to a production deployment.

Docker on any host

Dockerfile.example + cloud-run.example.yaml adapt to AWS Fargate, Azure Container Apps, GKE, a VM with Docker, or any container host.

Engine-only mode

Skip the DB and admin REST. Use idun agent serve --source file --path config.yaml when you have your own admin stack and only need the runtime.

Production hardening

The minimum production checklist: admin auth, TLS termination, bind address, Postgres, secrets management.

​
What you’re deploying

pip install idun-agent-engine produces one wheel containing:
  • The engine runtime (idun-agent-engine)
  • The standalone admin / chat / traces app (idun-agent-standalone)
  • The shared schema (idun-agent-schema)
  • The idun console script
In production you typically run idun serve inside a container, behind a TLS-terminating proxy or managed load balancer. SQLite is the default DB; Postgres is enabled by setting DATABASE_URL.

​
Docker on any host

The standalone wheel installs cleanly into any minimal Python 3.12 image. A typical Dockerfile looks like:
Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY . .

RUN pip install --no-cache-dir idun-agent-engine

ENV IDUN_HOST=0.0.0.0
ENV IDUN_PORT=8000

CMD ["idun", "serve"]
The standalone repo ships a Dockerfile.example and a cloud-run.example.yaml you can copy as a starting point. See Deploy to Cloud Run for the full walkthrough, including secrets management and the Cloud SQL annotations. For any other container host:
  • AWS Fargate / ECS: build the image, push to ECR, point the task definition at the image. Set IDUN_HOST=0.0.0.0 and the $PORT mapping to whatever the load balancer expects.
  • Azure Container Apps: same shape; set IDUN_HOST=0.0.0.0 and IDUN_PORT=80.
  • Kubernetes: a Deployment with one replica, a Service for the port, and a Secret for IDUN_ADMIN_PASSWORD_HASH + IDUN_SESSION_SECRET + DATABASE_URL is enough. Mount the secret as env. Scale to one replica per agent (the standalone is single-tenant).
  • A VM with Docker or Podman: copy the image, docker run with the env file and a reverse proxy in front.
For all of these, walk through Production hardening before opening the service to traffic.

​
Engine-only mode

If you have your own admin stack, your own observability, and your own deployment platform, skip the standalone DB / admin REST entirely: 
pip install idun-agent-engine
idun agent serve --source file --path config.yaml
No DB, no chat UI, no admin REST. The engine reads its YAML config at boot and serves /agent/run. Use this for CI/CD pipelines, headless integrations, or thin runtime workers that sit behind a control plane you already operate.

​
Next steps

Deploy to Cloud Run

The shortest managed path with HTTPS, autoscaling, and Cloud SQL Postgres.

Production hardening

Lock down admin auth, TLS, secrets, and trace retention before exposing the service.

CLI reference

Every flag and env var for idun serve, idun setup, and engine-only mode.
Last modified on May 20, 2026