Troubleshooting

Troubleshooting

Fixes for the errors and gotchas people most often hit self-hosting Termi. If your issue isn't listed here, check GitHub Discussions or open a bug report.

"ENCRYPTION_KEY environment variable is required"

You're missing (or have an empty) ENCRYPTION_KEY in your .env. Generate one and set it:

openssl rand -base64 32

This key encrypts every stored credential — see Security for why it's required rather than optional.

RDP/VNC connections fail, or guacd won't start on Apple Silicon

guacd (the Apache Guacamole daemon that powers RDP/VNC) has known FreeRDP struct-alignment bugs when emulated on ARM64. On Apple Silicon Macs, always start it with the native platform flag:

docker run -d -p 4822:4822 --name termi-guacd --platform linux/arm64 guacamole/guacd:1.6.0

RDP connects but credentials silently fail, or the server rejects the connection

Some Windows/RDP servers don't support Network Level Authentication (NLA), which causes credentials to fail without a clear error. In the server's connection settings, set RDP security mode to rdp instead of the default any — this bypasses NLA negotiation.

Auth/session errors after deploying the gateway separately from the web app

SESSION_SECRET, ENCRYPTION_KEY, and GATEWAY_JWT_SECRET must be identical between the web app and the gateway service — they're two processes that need to agree on the same secrets to validate each other's tokens. If you generated separate values for each service, connections will fail to authenticate. Set the same three values in both .env files.

"Can't connect to a server on my local network" (e.g. 192.168.x.x, 10.x.x.x)

This is intentional SSRF protection, not a bug — Termi blocks connections to private/internal IP ranges by default so a malicious "server" entry can't be used to probe your internal network. If you're self-hosting on a home network or homelab and want to manage local devices, set:

ALLOW_PRIVATE_NETWORKS=true

Only enable this if Termi itself is not exposed to the public internet.

Local terminal isn't available in the browser

The local terminal feature is opt-in for browser/cloud deployments (it's always available in the desktop app). To enable it on your self-hosted instance:

ALLOW_LOCAL_TERMINAL=true

Understand what this grants before enabling it: it lets anyone signed in to your instance open a shell on the machine running the gateway.

Wrong client IP in logs / rate limiting behaves oddly behind a reverse proxy

If Termi runs behind Traefik, Nginx, or another reverse proxy, set:

TRUSTED_PROXY=true

This tells Termi to read the real client IP from X-Forwarded-For instead of the proxy's own address.

Desktop app: "node-pty unavailable — local terminal disabled"

The bundled native module doesn't match your installed Electron version. Rebuild it:

npm run setup:electron

Run this once after any npm install in the Electron workspace.

macOS: "Apple could not verify 'Termi.app' is free of malware" / app is "damaged"

Expected — the desktop build is ad-hoc signed but not notarized (no paid Apple Developer ID). See Desktop App for the right-click-to-open and quarantine-removal fixes.

Windows SmartScreen warns about an unknown publisher

Also expected for the same reason. Click More info → Run anyway.

---

Related pages: Getting Started · Security · FAQ