# Environment Variables

Configuration for a self-hosted server. For the _agent’s_ variables, see [Agent Configuration](https://docs.shellhub.io/get-started/agent-configuration).

## Where to put them

Files are read in order, and the last one wins:

1. `.env` — the defaults. **Do not edit this**; an upgrade overwrites it.
2. `.env.enterprise` — Enterprise defaults, when the edition is not community.
3. `../cloud/.env` — when present, for Cloud deployments.
4. `.env.override` — **yours, and it wins over everything above.**

Put every change in `.env.override`.

```bash
# .env.override
SHELLHUB_DOMAIN=shellhub.example.com
SHELLHUB_AUTO_SSL=true
SHELLHUB_POSTGRES_PASSWORD=<not-admin>
```

## Network

| Variable                    | Default            | Meaning                                                                                                                                                                                                                                                                               |
| --------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SHELLHUB_BIND_ADDRESS`     | `0.0.0.0`          | Address the gateway binds                                                                                                                                                                                                                                                             |
| `SHELLHUB_HTTP_PORT`        | `80`               | HTTP port                                                                                                                                                                                                                                                                             |
| `SHELLHUB_HTTPS_PORT`       | `443`              | HTTPS port. **Only bound when `SHELLHUB_AUTO_SSL=true`**                                                                                                                                                                                                                              |
| `SHELLHUB_SSH_PORT`         | `22`               | SSH port. Published by the server, not the gateway                                                                                                                                                                                                                                    |
| `SHELLHUB_DOMAIN`           | `localhost`        | Public domain. Required for auto-SSL                                                                                                                                                                                                                                                  |
| `SHELLHUB_NETWORK`          | `shellhub_network` | Docker network name. Change to run several instances on one host                                                                                                                                                                                                                      |
| `SHELLHUB_NETWORK_EXTERNAL` | `false`            | Join `SHELLHUB_NETWORK` as an existing network instead of creating it. It must exist before the stack starts, and `down` leaves it in place                                                                                                                                           |
| `SHELLHUB_GATEWAY`          | `true`             | Run the gateway inside the server: it listens on the HTTP and HTTPS ports, obtains certificates, and serves the API, agent tunnels and web terminal with no proxy hop. Set `false` when a load balancer or Kubernetes ingress fronts the server, which then reaches it on port `8080` |

## TLS

| Variable                  | Default   | Meaning                                                          |
| ------------------------- | --------- | ---------------------------------------------------------------- |
| `SHELLHUB_AUTO_SSL`       | `false`   | Obtain certificates from Let’s Encrypt                           |
| `SHELLHUB_TLS_CERT_FILE`  | _(empty)_ | Path to your own certificate, inside the server container        |
| `SHELLHUB_TLS_KEY_FILE`   | _(empty)_ | Its key. **Set both or the gateway will not start**              |
| `SHELLHUB_ACME_CA_SERVER` | _(empty)_ | Alternative ACME directory. Empty means Let’s Encrypt production |

## Behind a proxy

| Variable                         | Default                                              | Meaning                                                                                                                                                     |
| -------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SHELLHUB_PROXY`                 | `false`                                              | Accept the PROXY protocol from a Layer 4 balancer                                                                                                           |
| `SHELLHUB_PROXY_TRUSTED_IPS`     | _(empty)_                                            | Space-separated CIDRs allowed to declare a client address, besides loopback. Required when `SHELLHUB_PROXY=true`                                            |
| `SHELLHUB_SSH_PROXY_TRUSTED_IPS` | _(empty)_                                            | Space-separated CIDRs allowed to send a PROXY protocol header to the SSH port, besides loopback                                                             |
| `SHELLHUB_PUBLIC_URL`            | built from `SHELLHUB_DOMAIN` and `SHELLHUB_AUTO_SSL` | URL users reach ShellHub at, such as `https://shellhub.example.com`. An `http` or `https` origin with no path                                               |
| `SHELLHUB_TUNNEL_PING_INTERVAL`  | _(empty)_                                            | How often the server pings each device’s tunnel, as a duration such as `15s`. Empty keeps each transport’s default, 30s on v1 tunnels and 35s on v2 tunnels |

ShellHub builds the links it hands out, such as invitation, confirmation and password-reset links, enrollment webhook callbacks, the SSH approval links in the terminal and the SAML URLs it sends an identity provider, from `SHELLHUB_DOMAIN`, with `https://` only when `SHELLHUB_AUTO_SSL=true`. When TLS ends at an ingress or load balancer in front of the gateway, set `SHELLHUB_PUBLIC_URL` so those links use `https://` without the gateway requesting certificates. Set it too when users reach ShellHub on a port `SHELLHUB_DOMAIN` does not name, such as `http://localhost:8080`, or the links leave the port out.

`SHELLHUB_PROXY_TRUSTED_IPS` decides the client address of web sign-in, device enrollment and web terminal sessions, so their lockout, firewall rules and access policy source IPs depend on it. A peer in those ranges, or on loopback, may name the client: in a PROXY protocol header when `SHELLHUB_PROXY=true`, or in `X-Real-IP` and `X-Forwarded-*` when it reaches port `8080`. Any other peer is taken to be the client. Empty, the default, trusts loopback alone. With `SHELLHUB_GATEWAY=false`, list your ingress or load balancer here, or every client appears to come from it. The server refuses to start with `SHELLHUB_PROXY=true` and no ranges, or with an entry that is not a CIDR range.

The SSH port reads only `SHELLHUB_SSH_PROXY_TRUSTED_IPS`, which decides the client address of SSH clients that connect to it. It closes a connection whose PROXY header comes from a peer outside those ranges and loopback, and logs a warning with that peer’s address. List your balancer’s range. Under Docker Compose, do not list the Docker bridge range: the userland proxy makes every external client appear to come from it, so any client could forge its address.

A NAT, load balancer or proxy that drops idle connections in under 30 seconds closes device tunnels between two pings. Set `SHELLHUB_TUNNEL_PING_INTERVAL` below its idle timeout. Each answered ping also marks the device as seen, and a device reads offline two minutes after the last one, so an interval above 40 seconds tolerates fewer than three missed pings. The server refuses to start on a value that is not a positive duration under one minute.

## Database

| Variable                        | Default    | Meaning                                                                                                                   |
| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| `SHELLHUB_DATABASE`             | `postgres` | Anything else warns and falls back to postgres                                                                            |
| `SHELLHUB_POSTGRES_HOST`        | `postgres` |                                                                                                                           |
| `SHELLHUB_POSTGRES_EXTERNAL`    | `false`    | Use a PostgreSQL outside this Compose project, at `SHELLHUB_POSTGRES_HOST`. The bundled `postgres` service does not start |
| `SHELLHUB_POSTGRES_PORT`        | `5432`     |                                                                                                                           |
| `SHELLHUB_POSTGRES_EXTRA_ARGS`  | _(empty)_  | Extra flags appended to the `postgres` command, for sizing the database to the host                                       |
| `SHELLHUB_POSTGRES_USERNAME`    | `admin`    | Note: `_USERNAME`, not `_USER`                                                                                            |
| `SHELLHUB_POSTGRES_PASSWORD`    | `admin`    | **Change this**                                                                                                           |
| `SHELLHUB_POSTGRES_DATABASE`    | `main`     | Note: `_DATABASE`, not `_DB`                                                                                              |
| `SHELLHUB_POSTGRES_LOG_LEVEL`   | `INFO`     |                                                                                                                           |
| `SHELLHUB_POSTGRES_LOG_VERBOSE` | `false`    |                                                                                                                           |

## Logging

| Variable                       | Default   | Meaning                                            |
| ------------------------------ | --------- | -------------------------------------------------- |
| `SHELLHUB_LOG_LEVEL`           | `info`    | `trace`, `debug`, `info`, `warn`, `error`, `fatal` |
| `SHELLHUB_LOG_FORMAT`          | `text`    | `text` or `json`                                   |
| `SHELLHUB_GATEWAY_ACCESS_LOGS` | `true`    |                                                    |
| `SHELLHUB_SENTRY_DSN`          | _(empty)_ |                                                    |

## Features and behavior

| Variable                                          | Default                       | Meaning                                                                                                                                                                                                            |
| ------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SHELLHUB_EDITION`                                | `community`                   | `community`, `enterprise`, or `cloud`                                                                                                                                                                              |
| `SHELLHUB_VERSION`                                | the release you checked out   | Which image tag to run                                                                                                                                                                                             |
| `SHELLHUB_METRICS`                                | `false`                       | Record HTTP request metrics alongside the server’s own                                                                                                                                                             |
| `SHELLHUB_METRICS_ADDRESS`                        | `127.0.0.1:9091`              | Address the server publishes its Prometheus metrics on, at `/metrics`. Clients never reach it: set `:9091` for a scraper on another host or container, and keep the port off the internet                          |
| `SHELLHUB_PAYWALL`                                | `true`                        | Show Cloud/Enterprise features to Community users                                                                                                                                                                  |
| `SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT`                | `60`                          | Maximum lockout minutes after repeated failed sign-ins, 0 disables                                                                                                                                                 |
| `SHELLHUB_ACCOUNT_LOCKOUT_BASE`                   | `1m`                          | First lockout’s length as a Go duration, at least `1s`; each later one is four times longer                                                                                                                        |
| `SHELLHUB_PERMIT_EMPTY_PASSWORDS`                 | `false`                       | Agent-side                                                                                                                                                                                                         |
| `SHELLHUB_REDIS_CACHE_POOL_SIZE`                  | `0`                           | 0 means the driver default                                                                                                                                                                                         |
| `SHELLHUB_WORKER_SCHEDULE`                        | `@daily`                      | Cron format                                                                                                                                                                                                        |
| `SHELLHUB_ASYNQ_UNIQUENESS_TIMEOUT`               | `24`                          | Hours; 0 or less disables uniqueness                                                                                                                                                                               |
| `SHELLHUB_ONBOARDING_URL`                         | the ShellHub survey workspace | Client API root of the survey workspace (`https://<host>/api/v1/client/<workspaceId>`); empty disables the survey                                                                                                  |
| `SHELLHUB_PROVISIONING_KEY_WEBHOOK_ALLOWED_CIDRS` | _(empty)_                     | Empty blocks all private, loopback and metadata addresses                                                                                                                                                          |
| `SHELLHUB_DEVICE_LIST_MAX_PAGE_SIZE`              | `1000`                        | Largest page a cursor read of `GET /api/devices` returns; a larger `page[size]` is lowered to it                                                                                                                   |
| `SHELLHUB_ALLOW_PUBLIC_KEY_ACCESS_BELLOW_0_6_0`   | `false`                       | Permit public-key auth from agents older than 0.6.0                                                                                                                                                                |
| `SHELLHUB_NAMESPACE_REQUIRE_VERIFIED_DEVICE_KEY`  | `true`                        | Whether a namespace created from now on starts with [Device signature enforcement](https://docs.shellhub.io/manage/settings#device-signature-enforcement) on. Namespaces that already exist keep their own setting |
| `SHELLHUB_TELEMETRY`                              | `true`                        | `false` turns [telemetry](https://docs.shellhub.io/selfhosted/telemetry) off and overrides the admin console setting. The server then opens no connection to the collector                                         |

> **Note**
>
> `SHELLHUB_ALLOW_PUBLIC_KEY_ACCESS_BELLOW_0_6_0` contains a misspelling — “BELLOW”. That is the real variable name. Reproduce it exactly.

## Device map and GeoIP

The Dashboard maps devices by the position of the address they connect from. The server image ships DB-IP City Lite, so positions work with no setup and no internet. When it can reach the internet, the server fetches DB-IP’s new database each month into `/data/geoip`.

| Variable                  | Default   | Meaning                                                                                                                                                              |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SHELLHUB_MAP_STYLE`      | `outline` | `outline` draws bundled country outlines and makes no outside request. `openfreemap` draws OpenFreeMap tiles. An `http(s)` URL points at your own MapLibre style     |
| `SHELLHUB_GEOIP_DATABASE` | `dbip`    | `dbip` uses DB-IP City Lite. `maxmind` uses MaxMind GeoLite2 (Enterprise and Cloud), with `SHELLHUB_MAXMIND_LICENSE` or `SHELLHUB_MAXMIND_MIRROR` as its credentials |
| `SHELLHUB_GEOIP_UPDATE`   | `true`    | `false` stops the monthly DB-IP download, and the server keeps the database it has                                                                                   |

When `maxmind` cannot load, the server falls back to DB-IP and logs a warning. The map credits the database the server actually uses.

DB-IP City Lite is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The map credits it as “IP Geolocation by DB-IP”, linked to [db-ip.com](https://db-ip.com/).

## Enterprise

From `.env.enterprise`, and only meaningful when the edition is not community.

| Variable                                    | Default                         | Meaning                                 |
| ------------------------------------------- | ------------------------------- | --------------------------------------- |
| `SHELLHUB_ENTERPRISE_ADMIN_USERNAME`        | _(empty)_                       | Enterprise Admin Console                |
| `SHELLHUB_ENTERPRISE_ADMIN_PASSWORD`        | _(empty)_                       |                                         |
| `SHELLHUB_SAML_SECRET`                      | _(empty)_                       | Encrypts the SP’s X.509 private key     |
| `SHELLHUB_WEB_ENDPOINTS`                    | `false`                         | Enable web endpoints                    |
| `SHELLHUB_WEB_ENDPOINTS_DOMAIN`             | falls back to `SHELLHUB_DOMAIN` | Domain endpoints are published under    |
| `SHELLHUB_WEB_ENDPOINTS_DNS_PROVIDER`       | `digitalocean`                  | DigitalOcean, Cloudflare, or `acme-dns` |
| `SHELLHUB_WEB_ENDPOINTS_DNS_PROVIDER_TOKEN` | _(empty)_                       | Required with auto-SSL                  |
| `SHELLHUB_OBJECT_STORAGE_ENDPOINT`          | `http://minio:9000`             | Session recording storage               |
| `SHELLHUB_OBJECT_STORAGE_REGION`            | `default`                       |                                         |
| `SHELLHUB_OBJECT_STORAGE_BUCKET`            | `shellhub`                      |                                         |
| `SHELLHUB_OBJECT_STORAGE_ACCESS_KEY`        | `username`                      | **Change this**                         |
| `SHELLHUB_OBJECT_STORAGE_SECRET_KEY`        | `password`                      | **Change this**                         |
| `SHELLHUB_MAXMIND_MIRROR`                   | _(empty)_                       | GeoIP source                            |
| `SHELLHUB_MAXMIND_LICENSE`                  | _(empty)_                       |                                         |

## Applying changes

```bash
$ make restart
```

## Where to go next

- [Ports and Connectivity](https://docs.shellhub.io/about/ports-and-connectivity) — What the network variables mean in practice.
- [Backup](https://docs.shellhub.io/selfhosted/backup) — Using the database credentials above.
