Minimal runtime dependencies for TLS/certs and basic health tooling.

RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates curl \ && rm -rf /var/lib/apt/lists/*

COPY pyproject.toml README.md /app/ COPY lumen /app/lumen

RUN pip install --no-cache-dir .

EXPOSE 3000

Docker / Docker Compose

Lumen can run as a containerized service using Docker Compose.

This is useful for:

• VPS deployments
• Dokploy
• Coolify
• CapRover
• Portainer
• internal infrastructure
• long-running agent services

Dockerfile

Create a Dockerfile in the repository root:

```dockerfile FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1

WORKDIR /app

Persist Lumen instance data in /root/.lumen using a Docker volume.

CMD ["lumen", "server", "--host", "0.0.0.0", "--port", "3000"] ```

Basic `docker-compose.yml`

Use this for a simple local/VPS Docker deployment:

services:
  lumen:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - lumen_data:/root/.lumen
    restart: unless-stopped

volumes:
  lumen_data:

Run:

docker compose up -d --build

Check logs:

docker compose logs -f lumen

Health check:

curl http://localhost:3000/health

Expected response:

{"ok": true}

The response may also include version, ready module count, model and provider status.

---

First Docker setup

On a fresh Docker volume, Lumen may need initial model/provider configuration before the server can fully start.

If the container keeps restarting and logs show something like:

¿Qué modelo querés usar?
1. DeepSeek
2. OpenAI GPT-4o-mini
3. Anthropic Claude
4. Ollama
5. OpenRouter
Aborted.

it means Lumen is waiting for the first interactive setup, but Docker cannot answer prompts in detached mode.

Fix: run one interactive setup against the same volume

1. Find the container name:

docker ps -a --format "table {{.Names}}\t{{.Status}}" | grep lumen

Example:

my-project-lumen-1   Restarting (1) 30 seconds ago

1. Save container, image and volume names:

C=my-project-lumen-1

IMG=$(docker inspect -f '{{.Config.Image}}' "$C")
VOL=$(docker inspect -f '{{range .Mounts}}{{if eq .Destination "/root/.lumen"}}{{.Name}}{{end}}{{end}}' "$C")

echo "IMG=$IMG"
echo "VOL=$VOL"

1. Stop the restart loop:

docker update --restart=no "$C"
docker stop "$C"

1. Run setup interactively using the same volume:

docker run --rm -it \
  -v "$VOL":/root/.lumen \
  "$IMG" \
  lumen server --host 0.0.0.0 --port 3000

1. Choose your provider/model.

Example choices:

2 = OpenAI GPT-4o-mini
5 = OpenRouter

1. When the configuration is saved and you see the server setup token, stop the temporary process with:

CTRL + C

The config is now stored in the Docker volume.

1. Re-enable restart policy and start again:

docker update --restart=unless-stopped "$C"
docker start "$C"

1. Verify:

curl http://localhost:3000/health

---

Dokploy deployment

Use Compose, not Application, when deploying Lumen to Dokploy.

Recommended Dokploy settings:

Create Service → Compose
Repository: your-lumen-agent-repo
Branch: main
Compose Path: ./docker-compose.yml

Domain settings:

Domain: your-domain.example.com
Service Name: lumen
Container Port: 3000
Internal Path: /
Strip Path: OFF
HTTPS: ON

Dokploy-compatible `docker-compose.yml`

Use this when Lumen must be reachable through Dokploy/Traefik and also be able to talk to other internal projects later.

services:
  lumen:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - lumen_data:/root/.lumen
    networks:
      - neuron-internal
      - dokploy-network
    restart: unless-stopped
    labels:
      - "traefik.http.middlewares.lumen-ratelimit.ratelimit.average=60"
      - "traefik.http.middlewares.lumen-ratelimit.ratelimit.period=1m"
      - "traefik.http.middlewares.lumen-ratelimit.ratelimit.burst=30"

      - "traefik.http.middlewares.lumen-secure-headers.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.lumen-secure-headers.headers.stsIncludeSubdomains=true"
      - "traefik.http.middlewares.lumen-secure-headers.headers.stsPreload=true"
      - "traefik.http.middlewares.lumen-secure-headers.headers.contentTypeNosniff=true"
      - "traefik.http.middlewares.lumen-secure-headers.headers.browserXssFilter=true"
      - "traefik.http.middlewares.lumen-secure-headers.headers.referrerPolicy=no-referrer-when-downgrade"

volumes:
  lumen_data:

networks:
  neuron-internal:
    external: true
  dokploy-network:
    external: true

Create the shared internal network once on the server:

docker network create neuron-internal

If the network already exists, Docker will print an error. That is safe to ignore.

Quickstart

pip install enlumen
lumen run

Your browser opens at:

http://localhost:3000

First time? The setup wizard walks you through three paths:

1. Quick start — default personality + free OpenRouter model.
2. Choose a personality — browse the catalog and pick one that matches your use case.
3. Bring your own module — upload a custom module.yaml to configure Lumen your way.

After that, Lumen awakens and you land directly in the chat. The sidebar gives you:

Charlas / Módulos / Memoria / Ajustes

No separate admin panel. No dev jargon.

Configuration

lumen config set <module>.<key> <value> [--instance <name>]
lumen config get <module>.<key> [--instance <name>]
lumen config delete <module>.<key> [--instance <name>]
lumen config list <module> [--instance <name>]

REST API

Lumen exposes a REST API for external integrations.

API key management

Generate a new API key:

lumen api-key generate --label "my app"

List keys:

lumen api-key list

Revoke a key by prefix:

lumen api-key revoke <prefix>

Inside Docker:

docker exec -it <lumen-container> lumen api-key generate --label "n8n"

Use the generated key in n8n as:

Authorization: Bearer <your-api-key>

The full key is shown only once.

---

CLI Reference

n8n integration pattern

Lumen works well as an agent runtime behind n8n.

Recommended flow:

Webhook / Trigger
↓
Neuron Guard checks input safety
↓
Honcho returns conversational memory
↓
Qdrant returns relevant security documents
↓
Redis caches short-lived expensive results
↓
n8n sends enriched message to Lumen /api/chat
↓
n8n stores useful result back into Honcho

Lumen should stay focused on:

agent reasoning
personality
modules
skills
chat execution
REST API responses

Use external services for shared infrastructure:

Honcho = long-term conversational memory
Qdrant = large semantic document search
Redis  = cache / temporary state / rate limits
n8n    = orchestration

---

Integration Modules

The catalog includes integration modules that connect Lumen with external services. Install like any other module.

Module management

lumen module install github:owner/repo
lumen module install https://github.com/owner/repo
lumen module install ./my-kit
lumen module install <catalog-name>

Module manifests

Lumen's native module manifest is module.yaml.

• module.yaml is preferred for all new modules
• manifest.yaml is supported as a legacy fallback
• x-lumen is an optional advisory namespace
• personality modules are detected by the personality tag, not by type

Example:

name: docs-helper
provides: [docs.answer]
requires:
  skills: [docs-helper]
x-lumen:
  requires:
    advisory:
      mcps: [docs-mcp]

If you are authoring a new module, start from:

lumen/modules/_template/module.yaml

---

Supported Models

Lumen uses LiteLLM as its model abstraction layer. Any provider supported by LiteLLM can work.

`lumen run` vs `lumen server`

Lumen has two startup modes depending on where it runs.

Troubleshooting