Configuration

Datalumo splits configuration into app config (JSON file) and secrets / infra (environment variables).

On this page

• Config file
  • Key sections
  • App types
  • Retrieval defaults
• Environment variables
  • Secrets (never put in config JSON)
  • Infrastructure overrides
  • Operational overrides (Docker-friendly)
• Authentication
• Spend and rate limits
• Production checklist

Config file

Path: datalumo.config.json in the working directory, or set DATALUMO_CONFIG=/path/to/config.json.

Start from the example:

cp datalumo.config.example.json datalumo.config.json

Minimal example:

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  },
  "vectorStore": { "type": "sqlite", "sqlite": { "path": "./data/datalumo.db" } },
  "stateStore": { "type": "sqlite", "sqlite": { "path": "./data/datalumo.db" } },
  "auth": { "mode": "apiKey" },
  "apps": [
    {
      "name": "support-bot",
      "indexes": ["docs"],
      "persona": "You are a helpful assistant. Cite sources.",
      "retrieval": { "k": 8, "minScore": 0.15 }
    }
  ]
}

Key sections

App types

Configured per app (or inferred):

Retrieval defaults

Per-app under retrieval:

{
  "retrieval": {
    "k": 8,
    "minScore": 0.15,
    "hybrid": false
  }
}

• minScore: cosine relevance floor (drops weak matches)
• hybrid: combine vector search with full-text (Postgres/SQLite)

Chat strategy

For chat and custom apps, under chat:

{
  "chat": {
    "mode": "agentic",
    "maxSteps": 4,
    "forceFirstSearch": false,
    "tools": ["search"]
  }
}

• oneshot (default): retrieve once, inject context, single LLM call
• agentic: the model calls the search tool and may refine across several steps

Managed apps can also set this in admin → Apps → Settings → Chat strategy.

Environment variables

Secrets (never put in config JSON)

Infrastructure overrides

Operational overrides (Docker-friendly)

These override datalumo.config.json. Useful in .env / compose without editing JSON:

Resolution order: defaults → config file → environment → programmatic (env wins over JSON).

Provider keys can also live in a .env file (auto-loaded by dl serve) or in /app/data/.env in Docker.

Manage via CLI:

dl env set OPENAI_API_KEY=sk-…
dl env list

Local and custom models

Datalumo can talk to any OpenAI-compatible endpoint through the custom provider: local servers (Ollama, vLLM, LM Studio) for a fully private, air-gapped setup, or hosted ones (DeepSeek, Groq, Together, OpenRouter).

Datalumo does not ship with a model. You run one as a separate service. If you host it on the same server, the model drives your hardware needs, not Datalumo. See Running a local model.

Point the LLM and embedding providers at the endpoint's base URL. The example below uses Ollama (ollama pull llama3.2 && ollama pull nomic-embed-text):

{
  "llm": { "provider": "custom", "model": "llama3.2", "baseUrl": "http://localhost:11434/v1" },
  "embedding": {
    "provider": "custom",
    "model": "nomic-embed-text",
    "dimensions": 768,
    "baseUrl": "http://localhost:11434/v1"
  }
}

Notes:

• Set embedding.dimensions to match the model (nomic-embed-text is 768). It's fixed once an index is created.
• The key is optional. Local servers ignore it; for a hosted endpoint set CUSTOM_API_KEY.
• You can mix providers, e.g. a hosted LLM with local embeddings, or vice versa.
• Env equivalents: DATALUMO_LLM_BASE_URL, DATALUMO_EMBEDDING_BASE_URL, CUSTOM_API_KEY.

Authentication

Full guide: Keys and access (admin keys, publishable keys, client tokens, spend caps).

The config side is small. Set the admin mode, and optionally fixed keys:

{ "auth": { "mode": "apiKey", "keys": ["your-secret-key"] } }

Or pass DATALUMO_API_KEYS=key1,key2. With no keys set, Datalumo generates one on first boot and saves it to /app/data/admin-key.

Allow your site's origin so the widget can call your instance:

{ "auth": { "cors": { "allowedOrigins": ["https://example.com"] } } }

Or DATALUMO_CORS_ORIGINS=https://example.com. Publishable-key origins are allowed automatically.

Spend and rate limits

Docker / .env (recommended for ops knobs):

DATALUMO_DAILY_TOKEN_CEILING=5000000
DATALUMO_PER_TOKEN_SPEND_CAP=200000
DATALUMO_RATE_LIMIT_MAX=120
DATALUMO_CORS_ORIGINS=https://example.com,https://www.example.com

Or in datalumo.config.json:

{
  "spend": { "dailyTokenCeiling": 5000000 },
  "auth": { "clientTokens": { "perTokenSpendCap": 200000 } },
  "rateLimit": {
    "enabled": true,
    "strategy": "redis",
    "window": "1m",
    "max": 120
  },
  "redis": { "url": "redis://redis:6379" }
}

• Daily ceiling: max prompt+completion tokens per UTC day (whole deployment)
• Per-token cap: max lifetime tokens per minted dlt_ token
• View usage vs limits in admin → System

Production checklist

In production (NODE_ENV=production or DATALUMO_ENV=production):

• auth.mode must be "apiKey"
• Set spend.dailyTokenCeiling
• Set auth.clientTokens.perTokenSpendCap when using publishable keys
• Keep rateLimit.enabled: true

Run dl config check or dl doctor to audit.

See Updates and backups for upgrade and snapshot procedures.