Deployment

Deploy Idun Agent Platform in standalone mode with a config file or as a managed stack with the Manager, database, and web UI.

Idun Agent Platform supports two deployment modes depending on your needs. You can run a single agent with a config file, or deploy the full platform with centralized management.

Deployment modes

Managed (full stack)

Deploy the Manager API, PostgreSQL database, and web UI together. Agents fetch their config from the Manager at startup.

Production (prebuilt images from Docker Hub):

git clone https://github.com/Idun-Group/idun-agent-platform.git
cd idun-agent-platform
cp .env.example .env
docker compose up

Development (builds from source, hot reload):

docker compose -f docker-compose.dev.yml up --build

Build from source (production images built locally):

docker compose -f docker-compose.build.yml up --build

This mode suits:

• Multi-agent deployments
• Teams that need centralized configuration
• Workspace isolation and RBAC
• Non-technical team members who prefer a UI

Standalone engine

Run a single agent from a YAML config file. No Manager, no database, no web UI required.

pip install idun-agent-engine
idun agent serve --source file --path config.yaml

This mode suits:

• Local development and testing
• Single-agent deployments
• CI/CD pipelines where you version config in Git

Docker Compose variants

File	Purpose	Images
docker-compose.yml	Production	Pulls prebuilt images from Docker Hub
docker-compose.build.yml	Build from source	Builds images locally from Dockerfiles
docker-compose.dev.yml	Development	Builds from source with hot reload, Vite dev server
docker-compose.debug.yml	Debug overlay	Adds debugpy to the manager (use with -f alongside dev)

All production and build compose files use env_file: .env for secrets and configuration. Copy .env.example to .env before starting.

To include the demo agent service, add the demo profile:

docker compose --profile demo up

Agent lifecycle management

Manager UI

From the agent detail page, manage the agent lifecycle:

• The status badge shows Draft or Active

• Click Restart to call /reload on the running engine, which re-fetches config from the platform

• The Overview tab includes Connect to Platform instructions for enrollment

  

Config file

With file-based deployment, manage your agent by restarting the process or updating the config file and restarting:

# Stop the running agent
pkill -f "idun agent serve"

# Update config.yaml, then restart
idun agent serve --source file --path config.yaml

For managed deployments, restart the agent container to force a fresh config fetch from the Manager.

Full stack architecture

In managed mode, the platform consists of three services and a database:

Component	Description	Default port
Manager	FastAPI control plane API for agent configuration, auth, and workspace management	8080
Web UI	React admin dashboard (nginx in production, Vite in dev)	3000
PostgreSQL	Stores agent configs, user accounts, workspace data	5432
Agent engines	Your agent services, each running the Idun engine SDK	8000+

Prerequisites

Requirement	Standalone	Managed
Python 3.12+	Yes	Yes (for agent services)
Docker + Docker Compose	No	Yes
PostgreSQL 16	No	Yes (included in Docker Compose)
idun-agent-engine package	Yes	Yes (for agent services)

Self-hosted cloud deployments

For production workloads, deploy the platform on your own cloud infrastructure.