Environment Variables
Configuration for a self-hosted server. For the agent’s variables, see Agent Configuration.
Where to put them
Files are read in order, and the last one wins:
.env— the defaults. Do not edit this; an upgrade overwrites it..env.enterprise— Enterprise defaults, when the edition is not community.../cloud/.env— when present, for Cloud deployments..env.override— yours, and it wins over everything above.
Put every change in .env.override.
# .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 on. Namespaces that already exist keep their own setting |
SHELLHUB_TELEMETRY |
true |
false turns telemetry off and overrides the admin console setting. The server then opens no connection to the collector |
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. The map credits it as “IP Geolocation by DB-IP”, linked to 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
$ make restart
Where to go next
- Ports and Connectivity — What the network variables mean in practice.
- Backup — Using the database credentials above.