> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Neuron

> Choose between the setup wizard, environment variables, and Gateway.config

A Neuron can be configured interactively, through environment variables, and through the runtime's `Gateway.config` module graph. Use each mechanism for the layer it owns.

| Mechanism             | Best for                                                        | Change behavior                                            |
| --------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| First-run pages       | Initial operator decisions and generated secrets                | Stored in the configured persistence layer or program data |
| Environment variables | Repeatable deployment inputs and secret injection               | Read during setup/startup; names are module-specific       |
| `Gateway.config`      | Runtime modules, event sinks, protocol extensions, web behavior | Requires validation and usually a restart                  |
| Admin UI              | Supported day-to-day configuration                              | Applies validation and persists through the owning module  |

## Environment variables

Environment variables allow the first-run sequence to be automated. The available variables come from the installed modules, so the definitive set for an installation is the set exposed by that build.

Common groups include:

* database provider, folder, encryption and connection settings;
* backup schedule and retention;
* domain, ports, certificates and Internet-gateway settings;
* XMPP account, federation and API-key settings;
* administrator and user provisioning;
* legal-identity, ledger, mail, theme and notification settings.

<Warning>
  Do not put passwords, API secrets, private keys, certificate passwords, or JWT secrets in a committed `.env` file. Inject them from a secret store and restrict access to the service process.
</Warning>

Use an installation-specific environment template as a checklist. Unknown variables can be ignored silently by some deployment wrappers, so verify the resulting state after startup.

## Edit Gateway.config safely

`Gateway.config` declares runtime modules and their configuration. Packages can add new elements, including event sinks, web resources, persistence providers, protocol handlers, and scheduled jobs.

1. Locate the active program-data folder from the running service.
2. Make a recoverable copy of `Gateway.config`.
3. Edit the file as UTF-8 XML.
4. Validate it against the schema shipped with the same build.
5. Restart the service.
6. Inspect the event log for module-load or XML-validation errors.

Avoid copying a configuration file between different Neuron versions without reviewing module and schema changes.

## Domain-specific web configuration

The web server can serve different content and policy for different domains. Use domain-specific configuration when a single Neuron terminates multiple host names. Keep authentication callbacks, OAuth redirect URIs, CSP, CORS, and canonical links aligned with the selected domain.

## Custom HTTP headers

Headers such as CORS, CSP, cache control, and security headers can be attached to web resources through the configured web-resource layer. Apply them to the narrowest resource scope possible. In particular:

* never combine `Access-Control-Allow-Origin: *` with credentialed browser access;
* keep API responses non-cacheable when they contain account or identity data;
* test CSP changes against Markdown-generated pages and package assets;
* do not override transport-security headers on plain HTTP.

## Configuration drift check

After each deployment, record:

```text theme={null}
Neuron build
Installed packages and versions
Configuration source revision
Certificate subject and expiry
Database provider
Enabled public listeners
Backup destination and last successful backup
```

This small manifest makes incident response and reproducible staging environments substantially easier.