Configuration Reference
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: { ... }, // full CORS override corsOrigins: [ ... ], // extra allowed origins for the default CORS policy sse: { ... }, // event stream replay buffer and heartbeat trace: false, // default: false (no run trace persistence)})enableAuth
Enables authentication. When false (the default), a local development user is created automatically and no login is required.
| Option | Env var | Default |
|---|---|---|
enableAuth |
LOOPSTACK_AUTH |
false |
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:
| Env var | Default | Effect |
|---|---|---|
LOOPSTACK_ALLOW_NO_AUTH |
— | Set to true to allow booting with authentication disabled while NODE_ENV=production. |
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.
| Option | Env var | Default |
|---|---|---|
database.host |
DATABASE_HOST |
localhost |
database.port |
DATABASE_PORT |
5432 |
database.username |
DATABASE_USERNAME |
postgres |
database.password |
DATABASE_PASSWORD |
admin |
database.database |
DATABASE_NAME |
postgres |
database.reuseExistingConnection |
— | false |
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. They are shared by the BullMQ job queues, the OAuth token and session stores, and the quota counters.
| Option | Env var | Default |
|---|---|---|
redis.host |
REDIS_HOST |
localhost |
redis.port |
REDIS_PORT |
6379 |
redis.password |
REDIS_PASSWORD |
— |
redis.db |
REDIS_DB |
0 |
Alternatively, set a single REDIS_URL (e.g. redis://host:6379/2) — common in managed and hosted environments. When present, it takes precedence over the discrete REDIS_* vars, and its path segment sets the database.
One database per deployment
A deployment is one AppModule with its own workflows and database, plus any replicas of it. Replicas share a Redis database on purpose: that is what makes them one worker pool for one task-queue.
Two different deployments must not share a database. Workers consume any job on task-queue, so a job can be handed to a process whose AppModule never registered that workflow. It cannot run it, and the run fails with a message naming this cause. The OAuth token store is keyed by user id with no deployment scope, so a shared database also means shared provider tokens.
Give each deployment its own database:
# deployment AREDIS_DB=0# deployment B, same Redis serverREDIS_DB=1Redis Cluster has no SELECT, and some managed providers expose only database 0. There, give each deployment its own Redis instance instead.
auth
JWT and hub authentication settings. Only relevant when enableAuth is true.
| Option | Env var | Default |
|---|---|---|
auth.jwt.secret |
JWT_SECRET |
required when auth is enabled |
auth.jwt.expiresIn |
JWT_EXPIRES_IN |
1h |
auth.jwt.refreshSecret |
JWT_REFRESH_SECRET |
value of JWT_SECRET |
auth.jwt.refreshExpiresIn |
JWT_REFRESH_EXPIRES_IN |
7d |
auth.jwt.cookieDomain |
JWT_COOKIE_DOMAIN |
unset (host-only cookies) |
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 |
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.jwt.cookieDomain sets the Domain attribute of the access and refresh cookies. Leave it unset unless a host other than the API must receive them — for example .example.com to share them across subdomains. The Studio sends cookies with every API request, so it works with host-only cookies on the API host.
cors
Full CORS override, passed straight to the cors middleware. When set it is used verbatim and corsOrigins is ignored. Set to false to disable CORS.
When cors is not set, a default policy with credentials: true is used. It allows:
- requests without an
Originheader (same-origin navigations and non-browser clients such ascurlor server-to-server calls); - any
http://orhttps://origin onlocalhost,127.0.0.1or[::1], on any port; - the origins listed in
corsOrigins.
Every other origin is rejected, so the browser blocks the response. Local development works without configuration; a deployment that serves Studio or another browser client from its own domain must add that origin to corsOrigins.
Do not set
cors: { origin: true, credentials: true }. It reflects any origin with credentials, letting every website make authenticated requests to your API on behalf of a signed-in user. UsecorsOriginsto allow specific origins instead.
corsOrigins
Extra origins allowed by the default CORS policy, in addition to localhost. Ignored when cors is set.
| Option | Env var | Default |
|---|---|---|
corsOrigins |
CORS_ORIGINS, falling back to FRONTEND_URL |
none (localhost only) |
The env vars are read only when corsOrigins is not set or empty, and take a comma-separated list. FRONTEND_URL is used only when CORS_ORIGINS is not set at all.
Origins are compared exactly against the browser’s Origin header — scheme, host and port, with no path or trailing slash:
LoopstackModule.forRoot({ corsOrigins: ['https://studio.example.com', 'https://app.example.com:8443'],});CORS_ORIGINS=https://studio.example.com,https://app.example.com:8443sse
Tuning for the server-sent-events stream at GET /api/v1/sse, which Studio and the TypeScript SDK subscribe to for live updates.
| Option | Env var | Default |
|---|---|---|
sse.bufferSize |
— | 1000 |
sse.bufferTtlMs |
— | 300000 (5 minutes) |
sse.heartbeatIntervalMs |
— | 25000 (25 seconds) |
LoopstackModule.forRoot({ sse: { bufferSize: 5000, bufferTtlMs: 15 * 60 * 1000, heartbeatIntervalMs: 15 * 1000 },});The server keeps recent events in a replay buffer per user and worker. A client that reconnects with a Last-Event-ID header (or lastEventId query parameter) receives the events it missed. bufferSize caps how many events are kept and bufferTtlMs how long. When the events after the client’s last ID are no longer buffered — evicted, or lost in a server restart — the client receives a single stream.reset event instead and has to refetch its state. Raise both if clients reconnect after long gaps.
Every heartbeatIntervalMs, the server sends a named ping event, which EventSource.onmessage consumers never see. It lets non-browser clients detect a dead connection and keeps the stream from looking idle to a reverse proxy — set it below any proxy idle timeout.
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.
| Option | Env var | Default |
|---|---|---|
trace |
LOOPSTACK_TRACE |
false |
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
| Env var | Default | Description |
|---|---|---|
NODE_ENV |
development |
Node.js environment |
DEFAULT_TRANSITION_TIMEOUT |
300000 |
Workflow transition timeout in milliseconds (5 minutes) |
API List Pagination
Page sizes for the list endpoints of the REST API, used when a request omits limit.
| Env var | Default | Description |
|---|---|---|
WORKFLOW_DEFAULT_LIMIT |
100 |
Default page size of GET /api/v1/workflows |
WORKSPACE_DEFAULT_LIMIT |
100 |
Default page size of GET /api/v1/workspaces |
DOCUMENT_DEFAULT_LIMIT |
100 |
Default page size of GET /api/v1/documents |
DOCUMENT_MAX_LIMIT |
500 |
Largest page GET /api/v1/documents serves; a larger limit is capped to this |
ADMIN_USER_DEFAULT_LIMIT |
100 |
Default page size of GET /api/v1/admin/users |
Only the document list has an upper bound. The workflow, workspace and admin user lists serve whatever limit a request asks for.
Scheduler
| Env var | Default | Description |
|---|---|---|
TASK_CONCURRENCY |
10 |
How many scheduler tasks one process runs at once (positive integer) |
SHUTDOWN_DRAIN_TIMEOUT_MS |
30000 |
How long a shutdown waits for in-flight runs to yield before closing the worker by force (ms) |
A workflow that occupies a task for its whole lifetime — a long-running agent session, for example — holds one of these slots, so leave headroom when running several. The value is exported from @loopstack/core as TASK_CONCURRENCY for apps that need to plan against it.
TASK_CONCURRENCY is read once, when @loopstack/core is imported — before LoopstackModule.forRoot() loads .env. A value in .env is therefore ignored. Set it in the process environment instead: in your shell, container or process manager, or with node --env-file=.env.
SHUTDOWN_DRAIN_TIMEOUT_MS bounds the graceful shutdown that app.enableShutdownHooks() enables. A run yields only between transitions, so a shutdown that arrives during a long transition — a container build, a clone, a command on a remote host — waits for it. Past the deadline, or on a second SIGINT/SIGTERM, the worker closes by force: the queue redelivers the interrupted jobs after restart and re-runs the cut-off transition from its checkpoint, the same recovery a crash takes. Raise the value for apps whose transitions legitimately run longer than 30 seconds and whose re-run would be costly. A container runtime kills the process at the end of its own grace period regardless (Docker after 10 seconds by default, Fly after 5), so a longer drain only takes effect where that grace period is raised with it. Read at shutdown time, so a value in .env works.
LLM Providers (examples)
Set these when using the corresponding LLM provider modules.
| Env var | Module | Description |
|---|---|---|
ANTHROPIC_API_KEY |
@loopstack/claude |
Anthropic API key |
OPENAI_API_KEY |
@loopstack/openai |
OpenAI API key |
CLAUDE_MODEL |
@loopstack/claude |
Default model fallback |
OPENAI_MODEL |
@loopstack/openai |
Default model fallback |
See LLM Providers for how these combine with module-level and per-call models.
OAuth Providers (examples)
Set these when using OAuth modules for third-party integrations.
| Env var | Module | Description |
|---|---|---|
GITHUB_CLIENT_ID |
@loopstack/github |
GitHub OAuth app client ID |
GITHUB_CLIENT_SECRET |
@loopstack/github |
GitHub OAuth app client secret |
GITHUB_OAUTH_REDIRECT_URI |
@loopstack/github |
GitHub OAuth redirect URI |
GOOGLE_CLIENT_ID |
@loopstack/google-workspace |
Google OAuth client ID |
GOOGLE_CLIENT_SECRET |
@loopstack/google-workspace |
Google OAuth client secret |
GOOGLE_OAUTH_REDIRECT_URI |
@loopstack/google-workspace |
Google OAuth redirect URI |
Registry Packages
Set these when using the corresponding registry packages.
| Env var | Module | Default | Description |
|---|---|---|---|
WORKSPACE_BASE_PATH |
@loopstack/local-file-explorer |
process.cwd() |
Root directory the file explorer lists and reads; paths outside it are rejected |
CLAUDE_WEB_FETCH_MODEL |
@loopstack/web |
claude-haiku-4-5-20251001 |
Model WebFetchTool summarizes with when called with a prompt and the provider is claude; its model arg wins |
QUOTA_ENABLED |
@loopstack/quota |
false |
Set to true to enable quota tracking |
QUOTA_REDIS_HOST |
@loopstack/quota |
value of REDIS_HOST |
Redis host for quota counters |
QUOTA_REDIS_PORT |
@loopstack/quota |
value of REDIS_PORT |
Redis port for quota counters |
QUOTA_REDIS_PASSWORD |
@loopstack/quota |
value of REDIS_PASSWORD |
Redis password for quota counters |
QUOTA_REDIS_DB |
@loopstack/quota |
value of REDIS_DB |
Redis database for quota counters |
The QUOTA_* variables are read only when the module is registered with QuotaModule.forRootAsync() — see @loopstack/quota.
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 + Redisdocker 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:3000The VITE_API_URL variable tells Studio where your backend is running. It defaults to http://localhost:3000.