Configuration Overview

Alta VMS reads config.yaml from its working directory, then overlays environment variables on top. Environment variables always win over file values, so secrets can stay out of the config file.

When installed via altavms install, the working directory is /etc/altavms/ and the service loads:

• /etc/altavms/config.yaml — non-secret settings
• /etc/altavms/altavms.env — secrets, loaded as environment variables by systemd

A missing config.yaml is fine — the server falls back to built-in defaults (development mode, port 3303, database at ./data/altavms.db).

Configuration is validated at startup. Invalid values — non-positive timeouts, zero concurrencies, out-of-range TTLs — abort startup with a config: validate: error in the service journal that names the offending key.

Check a config edit before restarting with altavms config validate, or print the effective merged configuration (secrets redacted) with altavms config print — see the CLI Reference. altavms config print --reference prints every key, its default, and a description, with no installed config required.

sudo altavms config validate
sudo altavms restart

Environment selection

The env value (development, staging, or production) changes validation strictness:

Behaviour	development	production
CORS allowed_origins	wildcard / empty allowed	concrete origins required
jwt_secret	optional (ephemeral)	required
Encryption key	optional (stub)	required
Security headers / strict CSP	relaxed	enforced

staging follows the production column for the strict validations: concrete CORS origins, jwt_secret, and the encryption key are required there too.

Required in production

A production deployment needs these secrets and initial admin values. The installer generates them automatically:

/etc/altavms/altavms.env

ALTAVMS_ENCRYPTION_KEY=<base64 32 bytes>     # openssl rand -base64 32
ALTAVMS_AUTH_JWT_SECRET=<base64 32 bytes>    # openssl rand -base64 32
ADMIN_EMAIL=admin@localhost
ADMIN_PASSWORD=<password>

The JWT secret and encryption key must be two different values — startup fails if they are identical.

It also needs concrete CORS origins in config.yaml:

env: production
http:
  allowed_origins:
    - "https://vms.example.com"

Behind a reverse proxy

When Alta VMS sits behind a TLS-terminating proxy (nginx, Caddy, Traefik), leave http.secure_cookies: true and make sure the proxy forwards the original Host and the WebSocket/SSE upgrade headers. HSTS is enabled automatically when env: production; http.tls_enabled is no longer a configuration option.

Set http.secure_cookies: false only when users access Alta VMS directly over plain HTTP on a LAN. The URL the Alta server uses to reach Alta VMS for WHEP authorization is set explicitly per server (its callback base URL) when you add it — see Connect an Alta Server.

Database & migrations

The database is SQLite (WAL mode). Schema migrations run automatically on every startup — there is no separate migrate step, and migrations are forward-only: there’s no downgrade path. Use sudo altavms backup before an upgrade, so a backup is your rollback plan — see Backup & Restore.

See the full reference for every option and its environment variable.