Configuration

Loma is configured entirely through environment variables. The backend reads .env; the dashboard reads dashboard/.env. Start from the .env.example files in each directory. Use the same MongoDB database for both so a dashboard-created admin is visible to the backend API.

Backend environment

A minimal, useful backend .env:

# Core
APP_NAME=Loma
ENV=PROD
WEBHOOK_PORT=3000
PUBLIC_BASE_URL=http://<server-ip>:3001
LOMA_SETUP_TOKEN=<random-first-admin-token>

# Storage
OBSERVABILITY_MONGODB_URI=mongodb+srv://user:pass@cluster.example.com/
OBSERVABILITY_DB_NAME=loma_observability
LOMA_SKILL_ASSET_DIR=/var/lib/loma/skill-assets

# Agent runtime (see Agent runtime page)
OPENCODE_API_KEY=opencode-...
AGENT_DEFAULT_MODEL=opencode-go/deepseek-v4-flash

# Slack (see Slack app page)
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

Variable	Purpose
`APP_NAME`	Display name in the dashboard.
`ENV`	Set to `PROD` for any non-local deployment.
`WEBHOOK_PORT`	Backend listen port (default `3000`).
`PUBLIC_BASE_URL`	Public dashboard origin, used for links/redirects. Behind a proxy, set this to your public URL.
`LOMA_SETUP_TOKEN`	One-time token to create the first admin. Use the same value in the dashboard env.
`OBSERVABILITY_MONGODB_URI`	MongoDB connection string. Read-only in the dashboard.
`OBSERVABILITY_DB_NAME`	Database name (default `loma_observability`).
`LOMA_SKILL_ASSET_DIR`	Disk path for non-text skill assets. Back this up.
`OAUTH_ENCRYPTION_KEY`	Fernet key used to encrypt stored integration credentials.

Integration credentials (e.g. PYLON_API_KEY, LINEAR_API_KEY, GITHUB_WEBHOOK_SECRET) are optional — see Integrations. Missing optional credentials must never block startup.

Dashboard environment

AUTH_SECRET=<random-long-secret>
AUTH_PROVIDER=local
NEXT_PUBLIC_AUTH_PROVIDER=local
LOMA_SETUP_TOKEN=<same-as-backend>
OBSERVABILITY_MONGODB_URI=mongodb+srv://user:pass@cluster.example.com/
OBSERVABILITY_DB_NAME=loma_observability
AUTH_URL=http://<server-ip>:3001
BACKEND_URL=http://loma-backend:3000
NEXT_PUBLIC_API_URL=

BACKEND_URL is the internal address the dashboard uses to reach the backend over the Docker network — keep it internal even behind a reverse proxy. See Authentication for AUTH_* options. Generate secrets with openssl rand -base64 32.

Feature flags

Optional subsystems are off unless enabled:

LOMA_ENABLE_SCHEDULER=false   # scheduled flows / routines
LOMA_ENABLE_WEBHOOKS=true     # inbound webhooks + webhook flows
LOMA_ENABLE_METRICS=false     # metrics jobs

Enable LOMA_ENABLE_SCHEDULER to run scheduled flows, and keep LOMA_ENABLE_WEBHOOKS on for webhook flows and integration webhooks.

Editing config from the dashboard

The dashboard’s Environment admin page reads and writes the backend .env file directly, so operators can change configuration without SSH:

Sensitive values (anything containing SECRET, KEY, TOKEN, PASSWORD, ENCRYPTION) are masked; revealing a value requires an admin.
A few keys are read-only (OBSERVABILITY_MONGODB_URI, WEBHOOK_PORT, ENV).
Connection-type variables (Slack tokens, the Mongo URI, API keys) are read when clients initialize, so changing them takes effect on a service restart.

In Docker, mount the .env file into the backend container so the page can read and edit it (the included docker-compose.yml does this).