Tera Router

Configuration

Environment variables, make targets, and the built-in limits of the server and dashboard.

Server (apps/server)

The server reads these variables from the environment — every CLI flag falls back to its variable, so a container needs no argument list. make run exports apps/server/.env and passes explicit flags, which still win over the environment.

VariableDefaultNotes
MACHINE_ID— (required)Unique machine ID (16-bit number, must not be 0)
APP_SECRET— (required)Signs JWTs and derives the credential encryption key; a new install refuses fewer than 32 characters
PORT8080Port for the gateway + dashboard API
ENVdevelopmentdevelopment enables dev behavior (sample key seeding); the release image and Compose examples set production via the container env
DEBUGfalsetrue/1 enables debug mode
DATABASE_PATHterarouter.dbSQLite file location
MIGRATE_ON_BOOTfalseRun migrations on start; Compose examples pass true
SEED_ON_BOOTfalseSeed initial data (roles, admin, Default plan); Compose examples pass true
ADMIN_EMAILadmin@tera.localAdmin email; a change renames the existing admin on the next seed
ADMIN_PASSWORDadmin123 (dev)Admin password — required in production; a change is synced to the admin on the next seed
ADMIN_TOTP_RESET—Set to true to turn off the admin's two-factor auth on the next seed; unset it after signing in
CORS_ALLOWED_ORIGINS* (dev), empty (prod)Comma-separated origin list, e.g. http://localhost:5173,http://localhost:3001; empty means same-origin only
TRUSTED_PROXIES—Comma-separated proxy IPs/CIDRs trusted to supply X-Forwarded-For
RATE_LIMIT_EXEMPT_IPS—Comma-separated client IPs that bypass the dashboard rate limit
RESTRICTED_ACCESS_DISABLEDfalseSet to true to ignore the Restricted Access period without changing it, e.g. after locking yourself out; unset it once you are back in
API_URL— (same origin)Public API base URL injected into the served dashboard and written into agent skill guides; set it for a split origin or behind a proxy
APP_NAMEtera-router-serverApplication name
SENTRY_DSN—Enables error tracking when set
OIDC_ISSUER—OIDC issuer base URL (Pocket ID, Keycloak, …); enables dashboard SSO when all three are set
OIDC_CLIENT_ID—OIDC client ID
OIDC_CLIENT_SECRET—OIDC client secret
OIDC_PROVIDER_NAMESSOProvider display name on the login button ("Continue with Pocket ID")
OIDC_REDIRECT_URLderivedCallback URL registered at the provider ({public URL}/v1/auth/oidc/callback); set it when a proxy hides the public scheme or host
OIDC_REQUIRE_EMAIL_VERIFIEDtrueRefuse sign-ins whose email_verified claim is false or absent
OIDC_DISABLE_PASSWORD_LOGINfalseHide and refuse password and passkey sign-in so SSO is the only way in; applies only while OIDC is enabled
OIDC_LINK_EXISTING_ACCOUNTStrueLet an OIDC sign-in link itself to an existing account with the same email; off means only provisioned or already-linked accounts use SSO
OIDC_AUTO_PROVISIONtrueCreate a user account for an OIDC sign-in whose verified email matches none; off means an admin must create the account first
OIDC_ALLOWED_DOMAINS(empty)Comma-separated email domains allowed to sign in via SSO; empty allows all. Applies to every SSO sign-in, linked accounts included
HEADROOM_URLhttp://localhost:8787Default Headroom proxy for Settings → Token Saving; a URL saved in the dashboard overrides it
HEADROOM_PROXY_TOKEN—Bearer token sent to a Headroom proxy bound beyond loopback (e.g. a compose sidecar)

APP_SECRET is the house key

Provider credentials are encrypted with a key derived from APP_SECRET. Changing the secret makes every stored credential unreadable. Change it only before data exists, and keep it safe. Generate it with openssl rand -hex 32: a new install does not start with a secret shorter than 32 characters, and an existing one logs a warning.

Make targets (apps/server)

TargetNotes
make runRun the API server (reads .env)
make installSet up the Go toolchain
make migrate/upRun migrations
make migrate/downRoll back migrations
make migrate/refreshReset the database
make seedSeed production data
make seed/devSeed the "Dev" sample key (plaintext printed once)
make testTests
make vetStatic analysis
make build/apiBuild the server binary

Dashboard (apps/web-ui)

VariableDefaultNotes
API_URLhttp://localhost:8080API server address (dev only — in production the server's API_URL env wins)
VITE_APP_NAMETera RouterDisplay name

The dashboard runs on port 5173 (pnpm dev in apps/web-ui).

Built-in limits

LimitValue
Maximum request body size32 MiB
Server read timeout20 seconds
Server write timeout3 minutes
Unary request deadline90 seconds
Stream deadline3 minutes
SSE heartbeat15 seconds
Gateway concurrency (in-flight)100
Dashboard rate limit100 req/min per IP (/assets/ exempt)
Key verification cache5 minutes
Retries per request (max)10
Account cooldown (429 / auth fail)30 seconds / 5 minutes

On this page