Docker Compose

The full runtime stack runs a master instance (port 8080), a worker instance (Kafka consumer), and all backing infrastructure: Kafka, Redis, PostgreSQL, Qdrant, MinIO, Vault, and an OCI registry.

Prerequisites

• Docker and Docker Compose v2
• The alquimia-runtime repository cloned locally

Start the stack

1. Copy the environment file

   cp .env.example .env

   Edit .env and set at minimum:

   .env

   API_TOKEN=your-secret-token
   POSTGRES_USERNAME=alquimia
   POSTGRES_PASSWORD=alquimia
   KAFKA_SIGNING_KEY=<64-char-hex>

   Generate the signing key: python -c "import secrets; print(secrets.token_hex(32))"

2. Start all services

   docker compose up -d

   Services started:

   • runtime — master mode FastAPI app on port 8080
   • runtime-worker — worker mode Kafka consumer
   • kafka — Kafka broker (KRaft, no Zookeeper)
   • redis — Session state and distributed locks
   • db — PostgreSQL persistent storage and audit logs
   • qdrant — Vector store for RAG
   • minio — S3-compatible blob storage
   • vault — Secret management (dev mode)
   • registry — Local OCI registry for agent packages

3. Run database migrations

   docker compose exec runtime alembic upgrade head

4. Verify the stack is healthy

   curl http://localhost:8080/health/liveness
   # "OK"
   
   curl http://localhost:8080/health/readiness
   # "OK"

Send your first inference request

# Create an agentspace
curl -X POST http://localhost:8080/registry/ \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agents", "namespace": "local", "tag": "latest"}'

# Add an agent (see Quickstart for the full agent JSON)
curl -X POST "http://localhost:8080/registry/agent?agentspace_id=default" \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d @my-agent.json

# Submit an inference request
curl -X POST http://localhost:8080/event/infer/my-first-agent \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the capital of France?",
    "user_id": "user-1",
    "session_id": "session-abc"
  }'
# Returns: {"task_id": "task-...", "session_id": "session-abc", ...}

Stream the response:

curl -N http://localhost:8080/event/stream/<task_id> \
  -H "Authorization: Bearer your-secret-token"

Service ports

| Service | Port | Purpose | |---|---|---| | runtime | 8080 | Master API | | kafka | 9092 | Kafka broker (internal) | | redis | 6379 | State store | | db | 5433 (host) | PostgreSQL | | qdrant | 6333, 6334 | Vector store | | minio | 9222 (API), 9223 (console) | Blob storage | | vault | 8200 | Secrets (dev mode) | | registry | 5001 | OCI registry |

Caution

The compose vault service runs in dev mode with root token root. Never use this configuration in production. Provide a scoped Vault token via VAULT_TOKEN.

Local development with hot-reload

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

Source directories are volume-mounted so code changes take effect without rebuilding.

Run with a local LLM

# Ollama + TEI embeddings
docker compose -f docker-compose.yml -f docker-compose.ollama.yml -f docker-compose.tei.yml up

# vLLM
docker compose -f docker-compose.yml -f docker-compose.vllm.yml up

Stop the stack

docker compose down          # Stop containers, keep volumes
docker compose down -v       # Stop containers and delete volumes

Next steps

• Inference Endpoints reference — full API documentation
• Configuration Reference — all environment variables
• Kubernetes & OpenShift — deploy to a cluster

Source

• Alquimia-ai/alquimia-runtime — docker-compose.yml, .env.example
• Alquimia-ai/alquimia-core — SDK bundled inside the runtime image