> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/deploy/host-n8n/configure-n8n/manage-settings-using-environment-variables.md).

# Manage settings using environment variables

You can manage a subset of instance settings from environment variables, instead of configuring them through the UI. This is useful when you provision n8n instances automatically, such as through an internal deployment pipeline.

Each supported area has a dedicated environment variable named `<AREA>_MANAGED_BY_ENV`. Set this variable to `true` to activate environment variable management for that area. n8n then applies the related environment variables and locks the matching UI controls.

## How it works <a href="#how-it-works" id="how-it-works"></a>

When you set `<AREA>_MANAGED_BY_ENV` to `true`:

* n8n reapplies the settings from environment variables **on every startup**.
* The matching UI controls become **read-only**.

When `<AREA>_MANAGED_BY_ENV` is `false` (the default), n8n ignores the related environment variables, even if you set them.

{% hint style="info" %}
**Values persist when you turn off `*_MANAGED_BY_ENV`**

Setting `*_MANAGED_BY_ENV` back to `false` restores UI write access but keeps the values that were last applied. Edit them through the UI afterward if you want to change them.
{% endhint %}

{% hint style="info" %}
**Unexpected read-only UI controls**

If a setting appears as read-only and you didn't expect it, check whether the matching `*_MANAGED_BY_ENV` variable is `true` in your environment.
{% endhint %}

The supported areas and their activating variables:

* Instance owner: `N8N_INSTANCE_OWNER_MANAGED_BY_ENV`
* SSO: `N8N_SSO_MANAGED_BY_ENV`
* Security policy: `N8N_SECURITY_POLICY_MANAGED_BY_ENV`
* Log streaming: `N8N_LOG_STREAMING_MANAGED_BY_ENV`
* MCP: `N8N_MCP_MANAGED_BY_ENV`
* Community packages: `N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV`

{% hint style="info" %}
**Set `<AREA>_MANAGED_BY_ENV` to activate the group**

The other environment variables for an area have no effect unless `<AREA>_MANAGED_BY_ENV` is `true`. Set it to `true` to activate the group.
{% endhint %}

## Instance owner <a href="#instance-owner" id="instance-owner"></a>

{% hint style="info" %}
**Available from n8n v2.17.0**
{% endhint %}

Pre-provision the [instance owner](/deploy/host-n8n/configure-n8n/user-management.md) from environment variables instead of going through the in-app setup. To change the owner email after setup, see [Change the instance owner email for self-hosted n8n](/deploy/host-n8n/configure-n8n/change-instance-owner-email.md).

{% hint style="warning" %}
**`N8N_INSTANCE_OWNER_PASSWORD_HASH` must be a bcrypt hash**

This variable expects a pre-hashed bcrypt value. Setting a plaintext password breaks login.
{% endhint %}

| Variable                            | Type    | Default | Description                                                                                                                                                                                                       |
| ----------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_INSTANCE_OWNER_MANAGED_BY_ENV` | Boolean | `false` | Set to `true` to manage the instance owner from environment variables. When `true`, n8n overwrites the instance owner details below on every startup, locks the UI control for that user, and rejects API writes. |
| `N8N_INSTANCE_OWNER_EMAIL`          | String  | -       | Email address for the instance owner.                                                                                                                                                                             |
| `N8N_INSTANCE_OWNER_FIRST_NAME`     | String  | -       | First name for the instance owner.                                                                                                                                                                                |
| `N8N_INSTANCE_OWNER_LAST_NAME`      | String  | -       | Last name for the instance owner.                                                                                                                                                                                 |
| `N8N_INSTANCE_OWNER_PASSWORD_HASH`  | String  | -       | Bcrypt hash of the instance owner's password. Setting a plaintext password breaks login.                                                                                                                          |

{% hint style="warning" %}
**Owner email must be unique**

`N8N_INSTANCE_OWNER_EMAIL` must not already belong to another user on the instance. This setting updates the existing instance owner account; it doesn't transfer ownership to another existing user or merge user accounts. To use an email address that already belongs to another user, change or delete that user first so the email becomes available.
{% endhint %}

## SSO <a href="#sso" id="sso"></a>

{% hint style="info" %}
**Available from n8n v2.18.0**
{% endhint %}

{% hint style="info" %}
**Feature availability**

Single sign-on is available on Business and Enterprise plans.
{% endhint %}

Configure [single sign-on](/deploy/host-n8n/configure-n8n/security/configure-sso.md) from environment variables.

### Activation and shared settings <a href="#activation-and-shared-settings" id="activation-and-shared-settings"></a>

| Variable                         | Type                                                                   | Default    | Description                                                                                                                                                                                                                           |
| -------------------------------- | ---------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_SSO_MANAGED_BY_ENV`         | Boolean                                                                | `false`    | Set to `true` to manage SSO from environment variables. When `true`, n8n applies the SSO variables on every startup and locks the matching UI controls.                                                                               |
| `N8N_SSO_USER_ROLE_PROVISIONING` | Enum string: `disabled`, `instance_role`, `instance_and_project_roles` | `disabled` | How n8n provisions roles for users who sign in through SSO. `disabled` doesn't provision any roles. `instance_role` provisions the instance-level role only. `instance_and_project_roles` provisions both instance and project roles. |

### OIDC <a href="#oidc" id="oidc"></a>

| Variable                          | Type    | Default | Description                                                                                                                  |
| --------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `N8N_SSO_OIDC_LOGIN_ENABLED`      | Boolean | `false` | Whether to enable OIDC login.                                                                                                |
| `N8N_SSO_OIDC_CLIENT_ID`          | String  | -       | OIDC client ID issued by your identity provider.                                                                             |
| `N8N_SSO_OIDC_CLIENT_SECRET`      | String  | -       | OIDC client secret issued by your identity provider.                                                                         |
| `N8N_SSO_OIDC_DISCOVERY_ENDPOINT` | String  | -       | OIDC discovery endpoint URL (the `.well-known/openid-configuration` URL for your identity provider).                         |
| `N8N_SSO_OIDC_PROMPT`             | String  | -       | Optional OIDC `prompt` parameter to send with the authorization request, for example `login` or `consent`.                   |
| `N8N_SSO_OIDC_ACR_VALUES`         | String  | -       | Optional OIDC `acr_values` parameter. Use this to request a specific authentication context, for example a step-up MFA flow. |

### SAML <a href="#saml" id="saml"></a>

{% hint style="warning" %}
**SAML metadata variables are mutually exclusive**

Set either `N8N_SSO_SAML_METADATA` (inline XML) or `N8N_SSO_SAML_METADATA_URL` (URL), not both.
{% endhint %}

| Variable                     | Type    | Default | Description                                                                                                            |
| ---------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `N8N_SSO_SAML_LOGIN_ENABLED` | Boolean | `false` | Whether to enable SAML login.                                                                                          |
| `N8N_SSO_SAML_METADATA`      | String  | -       | SAML identity provider metadata as an XML string. Mutually exclusive with `N8N_SSO_SAML_METADATA_URL`; don't set both. |
| `N8N_SSO_SAML_METADATA_URL`  | String  | -       | URL to fetch SAML identity provider metadata from. Mutually exclusive with `N8N_SSO_SAML_METADATA`; don't set both.    |

## Security policy <a href="#security-policy" id="security-policy"></a>

{% hint style="info" %}
**Available from n8n v2.18.0**
{% endhint %}

Manage the instance security policy from environment variables, including MFA enforcement and personal space restrictions.

| Variable                                | Type    | Default | Description                                                                                                                                                                         |
| --------------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_SECURITY_POLICY_MANAGED_BY_ENV`    | Boolean | `false` | Set to `true` to manage the security policy from environment variables. When `true`, n8n applies the security policy variables on every startup and locks the matching UI controls. |
| `N8N_MFA_ENFORCED_ENABLED`              | Boolean | `false` | Whether to enforce two-factor authentication for all users (`true`) or not (`false`).                                                                                               |
| `N8N_PERSONAL_SPACE_PUBLISHING_ENABLED` | Boolean | `true`  | Whether users can publish from their personal space (`true`) or not (`false`).                                                                                                      |
| `N8N_PERSONAL_SPACE_SHARING_ENABLED`    | Boolean | `true`  | Whether users can share resources from their personal space (`true`) or not (`false`).                                                                                              |

## Log streaming <a href="#log-streaming" id="log-streaming"></a>

{% hint style="info" %}
**Available from n8n v2.19.0**
{% endhint %}

Manage [log streaming](/administer/observe-and-log/stream-logs-to-external-systems.md) destinations from environment variables. See [Configure using environment variables](/administer/observe-and-log/stream-logs-to-external-systems.md#configure-using-environment-variables) for the per-destination JSON shape.

| Variable                           | Type        | Default | Description                                                                                                                                                                 |
| ---------------------------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_LOG_STREAMING_MANAGED_BY_ENV` | Boolean     | `false` | Set to `true` to manage log streaming from environment variables. When `true`, n8n applies the log streaming variables on every startup and locks the matching UI controls. |
| `N8N_LOG_STREAMING_DESTINATIONS`   | JSON string | -       | JSON array of log streaming destinations. Each destination is an object with a `type` of `webhook`, `syslog`, or `sentry`, plus the configuration for that type.            |

## MCP <a href="#mcp" id="mcp"></a>

{% hint style="info" %}
**Available from n8n v2.20.0**
{% endhint %}

Manage [instance-level MCP access](/connect/connect-to-n8n-mcp-server.md) from environment variables.

| Variable                 | Type    | Default | Description                                                                                                                                                      |
| ------------------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_MCP_MANAGED_BY_ENV` | Boolean | `false` | Set to `true` to manage MCP settings from environment variables. When `true`, n8n applies the MCP variables on every startup and locks the matching UI controls. |
| `N8N_MCP_ACCESS_ENABLED` | Boolean | `false` | Whether to enable instance-level MCP access (`true`) or not (`false`).                                                                                           |

## Community packages <a href="#community-packages" id="community-packages"></a>

{% hint style="info" %}
**Available from n8n v2.21.0**
{% endhint %}

Manage the set of installed [community packages](/integrations/community-nodes/installation-and-management.md) from environment variables. n8n reconciles the installed packages against the list on every startup. Managed packages can't be uninstalled or updated through the UI.

`N8N_COMMUNITY_PACKAGES_ENABLED` must also be set to `true` (the default). When community packages are disabled, n8n ignores `N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV` and logs a warning.

| Variable                                | Type        | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV` | Boolean     | `false` | Set to `true` to manage installed community packages from environment variables. When `true`, n8n reconciles the installed packages against `N8N_COMMUNITY_PACKAGES` on every startup, installing missing packages, correcting versions, and **uninstalling any currently-installed packages that aren't in the list**. The **Community nodes** settings page becomes read-only: you can't install, update, or uninstall packages from the UI while this is enabled. |
| `N8N_COMMUNITY_PACKAGES`                | JSON string | -       | JSON array of community packages to install. Each entry is an object with a `name` (required) and optional `version` and `checksum` fields. You can also embed the version in the name as `<package-name>@<version>`. See [environment variable installation](/integrations/community-nodes/installation-and-management/environment-variable-installation.md) for the full per-field reference.                                                                      |

## Combined example <a href="#combined-example" id="combined-example"></a>

The following example configures an instance with all six areas managed by environment variables. It creates the instance owner, configures OIDC SSO, enforces MFA, registers a webhook log streaming destination, enables MCP access, and manages a community package.

```bash
# Instance owner <a href="#instance-owner" id="instance-owner"></a>
export N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true
export N8N_INSTANCE_OWNER_EMAIL=<owner-email>
export N8N_INSTANCE_OWNER_FIRST_NAME=<first-name>
export N8N_INSTANCE_OWNER_LAST_NAME=<last-name>
export N8N_INSTANCE_OWNER_PASSWORD_HASH=<bcrypt-hash>

# SSO using OIDC <a href="#sso-using-oidc" id="sso-using-oidc"></a>
export N8N_SSO_MANAGED_BY_ENV=true
export N8N_SSO_USER_ROLE_PROVISIONING=instance_role
export N8N_SSO_OIDC_LOGIN_ENABLED=true
export N8N_SSO_OIDC_CLIENT_ID=<client-id>
export N8N_SSO_OIDC_CLIENT_SECRET=<client-secret>
export N8N_SSO_OIDC_DISCOVERY_ENDPOINT=<discovery-url>

# Security policy <a href="#security-policy" id="security-policy"></a>
export N8N_SECURITY_POLICY_MANAGED_BY_ENV=true
export N8N_MFA_ENFORCED_ENABLED=true
export N8N_PERSONAL_SPACE_PUBLISHING_ENABLED=false
export N8N_PERSONAL_SPACE_SHARING_ENABLED=false

# Log streaming <a href="#log-streaming" id="log-streaming"></a>
export N8N_LOG_STREAMING_MANAGED_BY_ENV=true
export N8N_LOG_STREAMING_DESTINATIONS='[{"type":"webhook","url":"https://logs.example.com/n8n"}]'

# MCP <a href="#mcp" id="mcp"></a>
export N8N_MCP_MANAGED_BY_ENV=true
export N8N_MCP_ACCESS_ENABLED=true

# Community packages <a href="#community-packages" id="community-packages"></a>
export N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
export N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-foo","version":"1.2.3"}]'
```

## Set environment variables <a href="#set-environment-variables" id="set-environment-variables"></a>

For the supported ways to set environment variables, see [Configuration methods](/deploy/host-n8n/configure-n8n/basic-configuration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.n8n.io/deploy/host-n8n/configure-n8n/manage-settings-using-environment-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.