This page documents how n8n is configured at runtime: the @n8n/config package's GlobalConfig class and its nested config classes, the environment variable mapping system, the legacy convict schema, and how FrontendSettings are assembled and served to the browser. For the commands that consume this configuration at startup, see 7.2. For license-specific feature flags that gate behaviour, see 7.5.
Configuration in n8n has two layers:
@n8n/config ā the canonical, typed configuration layer. All new environment variables live here. GlobalConfig is a DI-injectable singleton composed of nested config classes, each mapped to a set of environment variables using property decorators.
Legacy convict schema (packages/cli/src/config/schema.ts) ā a thin residual schema kept only for backward compatibility with cloud hooks and for storing mutable runtime state (authenticationMethod, isInstanceOwnerSetUp). No new variables should be added here.
At the boundary between backend and frontend, FrontendService assembles a FrontendSettings object from GlobalConfig and License and serves it to the browser at startup.
@n8n/config ā GlobalConfigGlobalConfig is the root singleton. It lives in packages/@n8n/config/src/index.ts and is registered in the DI container via the @Config class decorator.
Configuration flow:
Sources: packages/@n8n/config/src/index.ts packages/@n8n/config/test/config.test.ts1-50
Three decorators drive the mapping system, defined in packages/@n8n/config/src/decorators.ts and exported from the package index:
| Decorator | Applied to | Effect |
|---|---|---|
@Config | Class | Marks the class as a config root; registers it with the DI container |
@Env('VAR_NAME') | Property | Reads process.env.VAR_NAME and coerces it to the property type |
@Env('VAR_NAME', zodSchema) | Property | Same, but validates via a Zod schema; invalid values fall back to the default with a console.warn |
@Nested | Property | Recursively instantiates the property's type as another config class |
@Env type coercion behaviour
boolean: accepts 'true', '1', 'TRUE'; anything else is falsenumber: parseInt / parseFloat; invalid strings warn and fall back to defaultstring[]: parsed as JSON array_FILE suffix support
Any @Env property that accepts a string can have its value read from a file by setting VARNAME_FILE to a file path. The file contents are read with fs.readFileSync and trimmed; leading/trailing whitespace triggers a console.warn.
packages/@n8n/config/test/config.test.ts500-541
GlobalConfig StructureThe diagram below maps every top-level property of GlobalConfig to its class and primary environment variable(s).
Sources: packages/@n8n/config/src/index.ts69-232
Each nested class lives in packages/@n8n/config/src/configs/. The table below lists every class, its file, and representative environment variables.
| Config Class | File | Key Env Vars |
|---|---|---|
AuthConfig | auth.config.ts | N8N_AUTH_COOKIE_SECURE, N8N_AUTH_COOKIE_SAMESITE |
DatabaseConfig | database.config.ts | DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_USER, DB_POSTGRESDB_PASSWORD, DB_POSTGRESDB_PORT, DB_TABLE_PREFIX |
EndpointsConfig | endpoints.config.ts | N8N_ENDPOINT_REST, N8N_ENDPOINT_WEBHOOK, N8N_ENDPOINT_HEALTH, N8N_METRICS, N8N_PAYLOAD_SIZE_MAX |
ExecutionsConfig | executions.config.ts | EXECUTIONS_MODE, EXECUTIONS_TIMEOUT, EXECUTIONS_DATA_PRUNE, N8N_CONCURRENCY_PRODUCTION_LIMIT |
LoggingConfig | logging.config.ts | N8N_LOG_LEVEL, N8N_LOG_OUTPUT, N8N_LOG_FILE_LOCATION |
SecurityConfig | security.config.ts | N8N_RESTRICT_FILE_ACCESS_TO, N8N_BLOCK_FILE_ACCESS_TO_N8N_FILES, N8N_CROSS_ORIGIN_OPENER_POLICY |
LicenseConfig | license.config.ts | N8N_LICENSE_SERVER_URL, N8N_LICENSE_AUTO_RENEWAL_ENABLED, N8N_LICENSE_ACTIVATION_KEY |
ScalingModeConfig | scaling-mode.config.ts | QUEUE_BULL_REDIS_HOST, QUEUE_BULL_REDIS_PORT, QUEUE_HEALTH_CHECK_ACTIVE |
TaskRunnersConfig | runners.config.ts | N8N_RUNNERS_MODE, N8N_RUNNERS_AUTH_TOKEN, N8N_RUNNERS_MAX_CONCURRENCY, N8N_RUNNERS_TASK_TIMEOUT |
GenericConfig | generic.config.ts | GENERIC_TIMEZONE, N8N_RELEASE_CHANNEL, N8N_GRACEFUL_SHUTDOWN_TIMEOUT |
SsoConfig | sso.config.ts | N8N_SSO_SAML_LOGIN_ENABLED, N8N_SSO_LDAP_LOGIN_LABEL, N8N_SSO_OIDC_LOGIN_ENABLED |
DiagnosticsConfig | diagnostics.config.ts | N8N_DIAGNOSTICS_ENABLED, N8N_DIAGNOSTICS_CONFIG_FRONTEND |
CacheConfig | cache.config.ts | N8N_CACHE_BACKEND, N8N_CACHE_REDIS_TTL, N8N_CACHE_MEMORY_MAX_SIZE |
SentryConfig | sentry.config.ts | N8N_SENTRY_DSN_BACKEND, N8N_SENTRY_DSN_FRONTEND |
NodesConfig | nodes.config.ts | NODES_INCLUDE, NODES_EXCLUDE, NODE_FUNCTION_ALLOW_BUILTIN, N8N_PYTHON_ENABLED |
WorkflowsConfig | workflows.config.ts | N8N_DEFAULT_WORKFLOW_NAME, N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION |
MultiMainSetupConfig | multi-main-setup.config.ts | N8N_MULTI_MAIN_SETUP_ENABLED, N8N_MULTI_MAIN_SETUP_TTL |
EventBusConfig | event-bus.config.ts | N8N_EVENTBUS_CHECKUNSENTINTERVAL, N8N_EVENTBUS_CRASHRECOVERYMODE |
TemplatesConfig | templates.config.ts | N8N_TEMPLATES_ENABLED, N8N_TEMPLATES_HOST |
PublicApiConfig | public-api.config.ts | N8N_PUBLIC_API_DISABLED, N8N_PUBLIC_API_SWAGGER_UI_DISABLED |
MfaConfig | mfa.config.ts | N8N_MFA_ENABLED |
DeploymentConfig | deployment.config.ts | N8N_DEPLOYMENT_TYPE |
AiConfig | ai.config.ts | N8N_AI_ENABLED, N8N_AI_TIMEOUT, N8N_AI_ALLOW_SENDING_PARAMETER_VALUES |
AiAssistantConfig | ai-assistant.config.ts | N8N_AI_ASSISTANT_BASE_URL |
AiBuilderConfig | ai-builder.config.ts | N8N_AI_BUILDER_API_KEY |
ChatHubConfig | chat-hub.config.ts | N8N_CHAT_HUB_EXECUTION_CONTEXT_TTL, N8N_CHAT_HUB_STREAM_STATE_TTL |
RedisConfig | redis.config.ts | N8N_REDIS_PREFIX |
DataTableConfig | data-table.config.ts | N8N_DATA_TABLE_MAX_SIZE |
VersionNotificationsConfig | version-notifications.config.ts | N8N_VERSION_NOTIFICATIONS_ENABLED, N8N_VERSION_NOTIFICATIONS_ENDPOINT |
DynamicBannersConfig | dynamic-banners.config.ts | N8N_DYNAMIC_BANNERS_ENABLED, N8N_DYNAMIC_BANNERS_ENDPOINT |
WorkflowHistoryConfig | workflow-history.config.ts | N8N_WORKFLOW_HISTORY_PRUNE_TIME |
WorkflowHistoryCompactionConfig | workflow-history-compaction.config.ts | (interval/batch settings) |
TagsConfig | tags.config.ts | N8N_WORKFLOW_TAGS_DISABLED |
HiringBannerConfig | hiring-banner.config.ts | N8N_HIRING_BANNER_ENABLED |
PersonalizationConfig | personalization.config.ts | N8N_PERSONALIZATION_ENABLED |
ExternalHooksConfig | external-hooks.config.ts | EXTERNAL_HOOK_FILES |
UserManagementConfig | user-management.config.ts | N8N_USER_MANAGEMENT_JWT_SECRET, N8N_USER_MANAGEMENT_EMAIL_MODE |
Sources: packages/@n8n/config/src/index.ts1-65 packages/@n8n/config/test/config.test.ts28-434
The test suite documents the exact behaviour for invalid inputs:
DB_LOGGING_MAX_EXECUTION_TIME=abcd): console.warn('Invalid number value for ...'), property set to its declared default.N8N_RUNNERS_MODE=non-existing-mode): console.warn('Invalid value for ...'), property set to its declared default.N8N_ENDPOINT_HEALTH=healthz): automatically transformed to /healthz._FILE value with whitespace: console.warn issued; whitespace is trimmed before use.packages/@n8n/config/test/config.test.ts543-619
packages/cli/src/config/schema.ts defines a small residual convict schema. It is marked @deprecated at the top of the file and is kept only for:
userManagement.isInstanceOwnerSetUp ā mutable runtime flag loaded from the database at startup.userManagement.authenticationMethod ā mutable state updated when LDAP/SAML is toggled.endpoints.rest ā bridges GlobalConfig into the convict API for cloud-hooks compatibility.ai.enabled / ai.allowSendingParameterValues ā similarly bridges GlobalConfig values.The convict instance is created and exported as config from packages/cli/src/config/index.ts. Callers use config.set(key, value) for mutation (e.g., when database settings are loaded at startup) and config.getEnv(key) for reads.
Sources: packages/cli/src/config/schema.ts packages/cli/src/config/index.ts packages/cli/src/commands/start.ts315-320
packages/cli/src/config/index.ts)When the module is first imported, it:
GlobalConfig from the DI container.globalConfig properties (e.g., disabling diagnostics in E2E tests, setting log level to 'silent' in unit tests).schema.process.env looking for *_FILE suffixed variables and calls config.set() with file contents (for convict-managed variables only; GlobalConfig handles its own _FILE logic separately).setGlobalState({ defaultTimezone: globalConfig.generic.timezone }).packages/cli/src/config/index.ts
FrontendSettings is the object sent from the backend to the browser at page load. It is defined in packages/@n8n/api-types/src/frontend-settings.ts and assembled by FrontendService in packages/cli/src/services/frontend.service.ts.
Sources: packages/cli/src/services/frontend.service.ts104-386 packages/@n8n/api-types/src/frontend-settings.ts
FrontendSettings Key Fields| Field | Source | Notes |
|---|---|---|
databaseType | globalConfig.database.type | 'sqlite' or 'postgresdb' |
endpointWebhook | globalConfig.endpoints.webhook | Path prefix for production webhooks |
endpointHealth | globalConfig.endpoints.health | Resolved with leading / |
executionMode | globalConfig.executions.mode | 'regular' or 'queue' |
timezone | globalConfig.generic.timezone | IANA timezone string |
logLevel | globalConfig.logging.level | Forwarded to browser console |
releaseChannel | globalConfig.generic.releaseChannel | Controls logo color |
enterprise.* | license.isXyzEnabled() | All populated from License |
license.environment | globalConfig.license.tenantId | 1 ā 'production' |
mfa.enabled | globalConfig.mfa.enabled | MFA toggle |
telemetry | globalConfig.diagnostics.* | RudderStack key + URL |
posthog.* | globalConfig.diagnostics.posthogConfig | PostHog key + host |
pruning.* | globalConfig.executions.pruneData* | Execution retention config |
security.* | SecurityConfig | blockFileAccessToN8nFiles etc. |
envFeatureFlags | process.env (prefix N8N_ENV_FEAT_) | Pass-through feature flags |
packages/cli/src/services/frontend.service.ts183-385 packages/@n8n/api-types/src/frontend-settings.ts66-233
PublicFrontendSettings ā Unauthenticated SubsetFrontendService.getPublicSettings(includeMfaSettings) returns a minimal subset of FrontendSettings for pages that do not require authentication (login page, setup page). It includes only:
settingsMode: 'public'defaultLocaleuserManagement (authenticationMethod, showSetupOnFirstLoad, smtpSetup)sso (SAML, LDAP, OIDC login flags)authCookie.securepreviewModeenterprise (SAML, LDAP, OIDC license flags)communityNodesEnabledmfa if includeMfaSettings is truepackages/cli/src/services/frontend.service.ts555-594
settings.store.ts)The browser-side Pinia store useSettingsStore (in packages/frontend/editor-ui/src/app/stores/settings.store.ts) fetches FrontendSettings at startup via GET /rest/settings. The store exposes computed properties for each setting and gates UI features:
useSettingsStore.isQueueModeEnabled ā settings.executionMode === 'queue'
useSettingsStore.isAiAssistantEnabled ā settings.aiAssistant.enabled && settings.aiAssistant.setup
useSettingsStore.isCommunityPlan ā license.planName === 'Community'
useSettingsStore.isTelemetryEnabled ā settings.telemetry.enabled
If settingsMode === 'public', the store skips populating most of the root store (no OAuth URLs, no webhook base URLs, etc.).
packages/frontend/editor-ui/src/app/stores/settings.store.ts22-300
During Start.init(), generateStaticAssets() processes editor-ui/dist/index.html and replaces compile-time placeholders with runtime values from GlobalConfig:
| Placeholder | Value |
|---|---|
%CONFIG_TAGS% | Base64-encoded <meta> tags for REST endpoint and Sentry config |
/{{BASE_PATH}}/ | globalConfig.path |
{{REST_ENDPOINT}} | globalConfig.endpoints.rest |
This happens once at startup; the resulting files are written to instanceSettings.staticCacheDir.
packages/cli/src/commands/start.ts123-187
GlobalConfig is ConsumedServices and commands obtain GlobalConfig through the DI container using constructor injection:
Individual nested config classes can also be injected directly (e.g., ExecutionsConfig, SecurityConfig, TaskRunnersConfig) when a service only needs one subsection. This is done in tests and in narrowly scoped services.
packages/cli/src/services/frontend.service.ts110-128 packages/cli/src/controllers/e2e.controller.ts163-175
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.