Skip to content
plugboard.appRequest a demo

Reference

Environment variables

Configuration lives in .env on a self-hosted install. Set it to mode 600 and never commit it.

Generate every secret fresh, per deployment. Never copy one from another install, from this page, or from a demo.

Terminal
openssl rand -base64 32
VariableDefaultNotes
NODE_ENVdevelopmentSet to production for anything real
APP_VERSIONStamped in at build time. Shown under Settings, Licence & billing, in Deployment diagnostics
RELEASE_CHANNELstablestable or beta. Determines which release is recommended, never causes an update
VariableNotes
DATABASE_URLPostgreSQL connection string. Required
Terminal
DATABASE_URL="postgresql://user:pass@localhost:5432/plugboard?schema=public"
VariableDefaultNotes
REDIS_URLredis://localhost:6379Optional. Only the legacy people-sync and digest worker uses it

Optional. Only needed for logos, photos and exports.

VariableNotes
S3_ENDPOINTAny S3-compatible endpoint
S3_REGION
S3_ACCESS_KEY
S3_SECRET_KEY
S3_BUCKET

The block most often set wrong.

VariableNotes
PUBLIC_URLThe origin your users type, for example https://helpdesk.yourschool.org
PUBLIC_HOSTThe same hostname without the scheme
API_URLThe API origin
WEB_URLThe web origin
API_PORTDefault 4000
WEB_PORTDefault 3000

PUBLIC_URL (and WEB_URL) is the CORS allow-list, the base for every emailed link, the SSO redirect target and the portal address. Set it to an internal name and you generate links your users cannot open.

https://x, https://x/ and http://x are three different values as far as CORS is concerned.

VariableDefaultNotes
JWT_SECRETSigns session and refresh tokens. Rotating it logs everybody out
JWT_ACCESS_TTL15mAccess token lifetime
JWT_REFRESH_TTL30dRefresh token lifetime
VariableNotes
SECRETS_MASTER_KEY32-byte base64. Encrypts connector credentials and backups
Terminal
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Two options. Use a reverse proxy, or point the application at a certificate.

VariableNotes
TLS_CERT_FILEPEM certificate, including intermediates
TLS_KEY_FILEPEM private key
TLS_CA_FILEOptional intermediate chain, if your issuer ships one separately
TLS_PFX_FILEA PKCS#12 file, which is what most Windows tooling produces
TLS_PFX_PASSWORDIts password

Leave all unset to serve plain HTTP and terminate TLS at a proxy. See HTTPS and certificates.

VariableNotes
DEFAULT_TENANT_SLUGResolves a single default tenant when no subdomain matches. For single-tenant self-hosted installs
VariableNotes
INTERNAL_API_TOKENShared secret the worker uses to call internal endpoints
VariableDefaultNotes
PORTAL_USERNAME_ENTRY01 allows username-only entry at the kiosk and parent portal. Refused by default because typing a username proves nothing
PORTAL_SESSION_TTL_MS900000Portal session lifetime, 15 minutes
VariableDefaultNotes
ALLOW_PRIVATE_EGRESS01 allows outbound requests to private and loopback addresses. Link-local and cloud metadata addresses stay blocked

Blocks a tenant-supplied URL (a monitor target, a webhook, a connector base URL) from being used to reach internal hosts or a cloud metadata service.

Set it to 1 on an on-premises install that legitimately monitors LAN addresses. Leave it off for anything multi-tenant.

VariableDefaultNotes
SSE_MAX_STREAMS_PER_USER4Live-update streams one signed-in person may hold open at once
SSE_MAX_STREAMS_PER_TENANT200Live-update streams one school may hold open at once
SSE_MAX_STREAMS2000Live-update streams the whole deployment may hold open at once

The console holds one live-update stream open per signed-in tab, and every open stream asks the database every 30 seconds whether the person behind it is still signed in. The number of them is therefore a load on the same connection pool every other request is queueing for.

A stream past a ceiling is refused; the console backs off and tries again, so the tab recovers on its own once one closes. Four per person covers a technician with several tabs open and one the browser has not reaped yet.

Raise these on a large desk, and raise the database connection pool with them. Setting any of them to 0 or to something unparseable means “not configured” and leaves the default in place, so live updates cannot be switched off by mistake.

VariableNotes
LICENSE_KEYYour issued licence key
LICENSE_PUBLIC_KEYThe vendor’s Ed25519 public key, base64 SPKI PEM. Same for every customer
LICENSE_PUBLIC_KEYSA {kid: key} map, for key rotation
LICENSE_REVOKED_JTISComma-separated licence ids to refuse locally
LICENSE_SIGNING_SECRETLegacy HS256 shared secret. Needs LICENSE_ALLOW_LEGACY_HS256 as well
LICENSE_ALLOW_LEGACY_HS256Set to 1 to allow legacy HS256 keys at all. Off by default

Instances verify with the public key. The private half lives only on the vendor, so entitlement is checked offline and a network outage cannot disable a service desk.

Your deployment holds no licence signing key, and should not be given one. The older HS256 format is symmetric: the same secret that checks a licence can issue one. Both variables above must be set by hand before a legacy key will verify, and neither is set for you. They exist only to keep a school running mid-migration. If you are still on a v1 key, ask us for a reissued Ed25519 one rather than setting these.

VariableDefaultNotes
TELEMETRY_ENDPOINTNormally comes from the licence. This is an override
DEPLOYMENT_EDITIONonpremonprem or saas
USAGE_REPORTER_DISABLED01 turns off reporting. Snapshots are still kept locally
USAGE_REPORTER_TICK_MS3600000Reporter loop interval

Only counts are reported: technician accounts, managed devices, enabled modules, version. See licence and plan.

VariableNotes
DEMO_DISABLED_MODULESComma-separated module keys to hide on this deployment
Terminal
DEMO_DISABLED_MODULES=module.cardChecker,module.inductions

A blunt instrument: a module hidden this way cannot be re-enabled from the interface.

Seeds the SMTP connector on first start, so a fresh install can send email before anybody opens the connectors screen.

VariableNotes
SMTP_HOST
SMTP_PORT587 for STARTTLS, 465 for implicit TLS
SMTP_USER
SMTP_PASSWORD
SMTP_FROMFor example ICT Service Desk <[email protected]>

Beyond the initial setup, email is configured as a connector.

VariableDefaultNotes
LOCAL_AI_URLThe only setting needed to turn local AI on. Set it and first run creates an enabled AI connector pointing at it, for every institution that has none
LOCAL_AI_MODELqwen2.5:3bAny Ollama model on that host
OLLAMA_URLOlder name, still read
OLLAMA_MODELOlder name, still read

The installer sets these for you. They are here for pointing the deployment at a model you host somewhere else.

Leave LOCAL_AI_URL blank and the desk runs without a model: Ask answers from the desk’s own records, triage runs on rules, and the features that need a model are not shown.

Do not go below 3B. The 1B-class models fail the closed-list checks that triage answers are held to, often enough to be worse than no model at all.

See the bundled model, and three ways to get a model for the alternatives.

VariableDefaultNotes
EMBED_ORIGINSemptyParent origins allowed to frame the app, comma-separated. Empty refuses all framing

Read per request, so one image serves every deployment. Leave it unset unless you are embedding the product in another page on purpose.

VariableDefaultNotes
HSTS_MAX_AGE31536000Seconds a browser should refuse plain HTTP for this hostname. 0 sends no Strict-Transport-Security header at all

Both the API and the web app read this and send the header themselves, so it applies whatever sits in front of them: a reverse proxy, a tunnel, or nothing. Browsers only honour it over HTTPS, so a plain-HTTP install does not need to change it.

Set it to 0 if this hostname must stay reachable over plain HTTP by design, or if your own proxy already sends the header and you want a single authority for the value.

Shortening or removing it is not retroactive. A browser that has already seen a year holds it for a year from the last time it saw it; only an HTTPS response carrying a smaller max-age updates that, and only when that browser next visits.

VariableDefaultNotes
CSP_ENFORCEunset1 (or true) enforces the desk’s script policy. Unset, the policy is sent as Content-Security-Policy-Report-Only: the browser reports what it would block and blocks nothing

The web app sends a script policy with a fresh nonce for every page, so a script injected into a page does not run once the policy is enforced. While it only reports, browsers send their reports to /api/csp-report, which counts them as plugboard_csp_reports_total on /api/metrics and never reads what they contain.

Watch that count after an update. When it stops rising through normal use, set CSP_ENFORCE=1 and restart. The endpoint counts at most 1,000 reports a minute, and never counts against any address’s request limit.

Framing is enforced either way. With EMBED_ORIGINS empty, X-Frame-Options: DENY refuses all framing. With an allow-list, the framing policy is an enforced header, and the script policy is not sent report-only beside it, so no reports arrive: set CSP_ENFORCE=1 to enforce the script policy too.

VariableDefaultNotes
AGENT_JOB_TTL_MS120000How long a queued job waits for an agent
AGENT_LONG_POLL_MS25000How long an agent holds the connection with nothing to do
AGENT_TOKEN_TTL_DAYS365How long a newly issued or rotated agent token is accepted for

See connector agents.

Two more are read by the agent itself, on the machine it runs on, rather than by the platform. AGENT_CONFIG and AGENT_SECRETS say where its agent.env and its secrets file are. AGENT_ALLOW_INSECURE_URL=1 lets it report to a plain http:// address, which it otherwise refuses. Only set it where TLS is terminated somewhere you trust on the same host, because the agent’s token is sent on every heartbeat.

On-premises bundle only.

VariableDefaultNotes
AUTO_UPDATEonoff to never update on its own
AUTO_UPDATE_HOUR1Local hour, 0 to 23
AUTO_UPDATE_RESTARTonoff to stage the update but apply at your next restart

Uses the machine’s own local time. A server set to UTC in a school that is not will update in the middle of a school day.

The local panel described in the status panel. On-premises bundle only.

VariableDefaultNotes
PANEL_HOST127.0.0.1The interface the panel binds to. Loopback by default
PANEL_PORT9090Change this if something else on the machine already has 9090
PANEL_TOKENgeneratedProtected installation-owner key, required on every interface including loopback. Used by the launcher to authenticate the panel; never put it in a browser URL
PANEL_ALLOWED_HOSTS(none)Extra hostnames the panel will answer to, comma separated. Needed only if you reach a non-loopback panel by name rather than by address

Open the panel with plugboard panel under the installation owner. The CLI verifies the listener and creates a one-use opening link valid for 30 seconds. The browser then needs both its session cookie and an exact-origin storage proof; the owner key is never sent to the browser. Sessions expire after eight hours or a panel restart. An empty owner key refuses authentication on loopback too. See status panel access for Linux service-owner and SSH-forwarding instructions.

The panel answers only to its own name. A request whose Host is not loopback, your PANEL_HOST, or a name you listed in PANEL_ALLOWED_HOSTS gets a 403 and nothing else, not even a cookie. That closes DNS rebinding, where a hostile page points its own hostname at 127.0.0.1 so the browser will treat the panel as same-origin with it and send the panel’s x-plugboard-panel request header for free. Action and log endpoints require that header, which a cross-origin page cannot send. Set PANEL_ALLOWED_HOSTS only for the names you actually use; it is read at start, so a change needs a restart.

Do not expose the panel anyway. It configures the deployment and can restart it.

VariableDefaultNotes
BACKUP_BASE_DIRthe working directoryThe root every backup path is contained under. The target directory set in Settings, Backups is resolved against this, and a path that lands outside it (absolute, or climbing out with ..) is refused when it is saved and again when a run starts

See backups and restore.

VariableNotes
SENTRY_DSNError reporting to your own self-hosted Sentry or GlitchTip. No default destination
METRICS_TOKENUnset, /api/metrics is open. Set it, and a scrape must send Authorization: Bearer <token>
BUILD_INFO_TOKENLets a holder read the git commit and the build timestamp from /api/health/version, which otherwise answers with the version and channel only. Unset (the default), nobody gets them. A missing or wrong token is answered with the short form rather than an error, so this can never stop a health check working

See keeping an eye on it.

VariableNotes
PLUGBOARD_DEMO_DATA1 seeds fictional sample data on a brand new database only
WEBHOOKS_DISABLED1 disables outbound webhook delivery
REPORTS_DISABLED1 disables the scheduled report loop
BACKUPS_DISABLED1 stops the scheduled backup loop from starting. Manual backups still work. Not for production