Configuration

Loopstack is configured via LoopstackModule.forRoot() options and environment variables. Environment variables are read from a .env file in your project root.

All settings have sensible defaults — a fresh project works out of the box with no configuration.

Need finer-grained control over the database connection, config loading, or which submodules are registered? See Custom Bootstrap for replacing LoopstackModule.forRoot() with its underlying modules.

LoopstackModule.forRoot() Options

LoopstackModule.forRoot({
  enableAuth: false,        // default: false (no authentication)
  database: { ... },        // PostgreSQL connection
  redis: { ... },           // Redis connection
  auth: { ... },            // JWT and hub auth settings
  cors: { ... },            // CORS configuration
})

enableAuth

Enables authentication. When false (the default), a local development user is created automatically and no login is required.

Set enableAuth: true or LOOPSTACK_AUTH=true to require authentication via Loopstack Hub.

Disabling authentication in production (advanced)

Running with authentication disabled means every request resolves to the shared local user, which is convenient for local development but exposes all non-role-gated data and actions to anyone who can reach the server. To prevent an accidental unauthenticated public deployment, Loopstack refuses to start when authentication is disabled and NODE_ENV=production.

If you intentionally run an unauthenticated instance in production — for example behind a trusted private network or an authenticating proxy — acknowledge it explicitly:

Outside production, disabling auth only logs a startup warning; no acknowledgment is required.

database

PostgreSQL connection settings. All fields are optional — defaults connect to a local PostgreSQL instance.

Alternatively, set a single DATABASE_URL (e.g. postgres://user:password@host:5432/dbname) — common in managed and hosted environments. When present (and no programmatic database options are passed), it takes precedence over the discrete DATABASE_* vars.

Set database.reuseExistingConnection: true to reuse the host application’s default TypeORM connection. When enabled, Loopstack skips its own TypeOrmModule.forRoot() registration and its repositories resolve against the default connection you registered — which must point at PostgreSQL and load Loopstack’s entities (e.g. autoLoadEntities: true).

redis

Redis connection settings for BullMQ job queues.

Alternatively, set a single REDIS_URL (e.g. redis://host:6379) — common in managed and hosted environments. When present, it takes precedence over the discrete REDIS_* vars.

auth

JWT and hub authentication settings. Only relevant when enableAuth is true.

When enableAuth is true, JWT_SECRET (and JWT_REFRESH_SECRET) must be set to a strong, unique value of at least 32 characters — the server refuses to start otherwise, and known/default values are rejected. When auth is disabled, an insecure development secret is used automatically (it never signs trusted tokens, since the local-user shortcut bypasses JWT verification). | auth.clientId | CLIENT_ID | local | | auth.hub.issuer | HUB_ISSUER | https://hub.loopstack.ai | | auth.hub.jwksUri | HUB_JWKS_URI | https://hub.loopstack.ai/.well-known/jwks.json |

cors

Standard NestJS/Express CORS options (the cors package). Defaults to { origin: true, credentials: true }. Set to false to disable CORS.

trace

Persist every run’s trace — transitions, tool calls with args and result envelopes, documents — as queryable rows, powering loopstack runs <id> --record for deriving replay fixtures.

Off by default: the in-memory trace always exists, but nothing is written to the database. Individual runs opt in with loopstack run <workflow> --trace (or trace: true on the start payload) — sub-workflows inherit the flag. Set trace: true / LOOPSTACK_TRACE=true to record every run, e.g. on a development backend.

Other Environment Variables

These are read directly from the environment and are not part of LoopstackModule.forRoot().

General

LLM Providers (examples)

Set these when using the corresponding LLM provider modules.

OAuth Providers (examples)

Set these when using OAuth modules for third-party integrations.

Docker Compose

The @loopstack/loopstack-module package ships with a Docker Compose file that starts PostgreSQL and Redis with settings that match the defaults above — no .env file needed for local development. Studio is a separate, optional compose file.

docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.yml up -d          # Postgres + Redis
docker compose -f node_modules/@loopstack/loopstack-module/docker-compose.studio.yml up -d   # Studio (optional)

To customize, create a .env file in your project root:

VITE_API_URL=http://localhost:3000

The VITE_API_URL variable tells Studio where your backend is running. It defaults to http://localhost:3000.