Docker Compose

Docker Compose is the fastest way to run Alquimia Platform locally. It starts the runtime together with the supporting services: Kafka, PostgreSQL, Redis, Qdrant, an S3-compatible object store (Alarik), Vault, and an OCI registry.

When to use this guide

• Local development and prototyping.
• Demonstrating the platform to stakeholders.
• Testing agent configurations before promoting them to a shared environment.

What runs

Service	Purpose
Runtime	Master (runtime, HTTP API) and worker (runtime-worker, agent execution) containers
Kafka	Event bus between master and worker roles
PostgreSQL	Persistent audit worklog and webhook subscriptions
Redis	Session state, caches, and locks
Qdrant	Vector store for knowledge bases
Alarik	S3-compatible blob storage for attachments
Vault	Secret storage and dynamic credentials
OCI registry	Storage for agent packages and Boltzmann Brains
Studio	Web UI for designing, testing, and managing agents (runtime 0.5.1+)

Get started

1. Clone the alquimia-runtime repository.
2. Copy the example environment file and fill in the required secrets.
3. Start the stack with Docker Compose.
4. Verify the runtime health endpoint responds.

The Compose file runs the master (ALQUIMIA_RUNTIME_MODE=master) and a worker (ALQUIMIA_RUNTIME_MODE=worker) as separate containers that share the local registry directory, mounted read-only in the worker. For a single-process setup, run one container with ALQUIMIA_RUNTIME_MODE=all; this is convenient for local work but not recommended for production.

Note

Production deployments should run master and worker as separate deployments: a single master replica and as many worker replicas as you need for throughput.

Environment setup

At minimum you will need:

• An API token for authenticating requests.
• Database credentials for PostgreSQL.
• A Vault token for secret resolution (local Compose uses VAULT_AUTH_METHOD=token).
• Object-store credentials for the local S3-compatible store or S3.
• A signing key for CloudEvent integrity.

Tip

The local compose exposes Alarik on host port 9222 (S3 API) and 9223 (console). Point BLOB_S3_ENDPOINT_URL at http://alarik:8080 inside the compose network. Keep BLOB_S3_PROVIDER=Minio — this is rclone’s generic S3-compatible provider name and is correct for Alarik as well.

• An LLM provider API key if you want to run real inferences.

Store these values in the environment file; never commit secrets to source control.

Next steps

• Register your first agent
• Kubernetes & OpenShift — move to a production-grade deployment.
• Configuration — understand the runtime configuration model.

Tip

For exact commands, environment-variable reference, and the Docker Compose manifest, see the Runtime configuration reference.