Configuration

Quazzar Cloud OS is configured through two files:

Configuration File

quazzar.service reads /etc/quazzar/quazzar.env through systemd’s EnvironmentFile=. Edit it with:

sudo nano /etc/quazzar/quazzar.env

Changes apply after a restart:

sudo systemctl restart quazzar

The file uses systemd’s format: one KEY=value per line, no export, no spaces around =, # starts a comment. Shell syntax such as $HOME is not expanded.

What the package installs

The quazzar package (.deb or .rpm) installs /etc/quazzar/quazzar.env as a template, owned by root:quazzar with mode 0640. Every variable the node reads is listed there, commented out, with its default value and a one-line explanation. To change a setting, uncomment its line and edit the value.

Only these lines are active after a fresh install:

QUAZZAR_ADDR=:8080                        # legacy, not read (see below)
QUAZZAR_DATA_DIR=/var/lib/quazzar
QUAZZAR_LOG_LEVEL=info
DOCKER_HOST=unix:///var/run/docker.sock

QUAZZAR_JWT_SECRET is commented out: the node generates its own random session secret. Older packages shipped an active QUAZZAR_JWT_SECRET=CHANGE_ME placeholder; see JWT signing secret for what happens to it now.

QUAZZAR_ADDR is still in the file so existing files stay unchanged, but current releases do not read it. Set the listen port with QUAZZAR_PORT or server.port in quazzar.yaml.

Preserved on upgrade

/etc/quazzar/quazzar.env and /etc/quazzar/quazzar.yaml are package configuration files: dpkg conffiles on Debian/Ubuntu, %config(noreplace) on RPM distros.

• If you have not edited the file, an upgrade replaces it with the new template. Your active lines are the same as before, and new variables appear as commented-out lines.
• If you have edited the file, an upgrade keeps your copy and saves the new template next to it as quazzar.env.dpkg-dist (Debian/Ubuntu) or quazzar.env.rpmnew (RPM). Compare the two with diff to see new variables.

The in-app updater and install.sh keep your copy without asking. A manual sudo apt upgrade asks what to do about a changed configuration file: press Enter (the default, N) to keep yours.

JWT signing secret

The JWT signing secret signs session cookies. By default you do not set it: the node generates a random secret on first start and persists it to disk at $QUAZZAR_DATA_DIR/jwt-secret (default /var/lib/quazzar/jwt-secret, mode 0600), so sessions survive apt upgrade and restarts.

Set QUAZZAR_JWT_SECRET only to pin a secret, for example when your orchestrator manages it. It must be at least 32 random characters:

QUAZZAR_JWT_SECRET=<output of: openssl rand -hex 32>

A strong value set in the environment wins and the file is ignored. A weak value is ignored: the node logs an error and uses the persisted random secret instead. Weak means, after trimming whitespace and ignoring case, a known placeholder (CHANGE_ME, changeme, change-me, secret, <64-byte hex string>), empty, or shorter than 32 characters.

Older packages shipped an active QUAZZAR_JWT_SECRET=CHANGE_ME. Because that value is public, anyone could forge session tokens on a node that kept it. The package upgrade comments that exact line out in /etc/quazzar/quazzar.env (a real secret is never touched), and quazzard ignores it even if it is still there. Check a node with:

grep JWT_SECRET /etc/quazzar/quazzar.env

Passkey domain

Passkeys are tied to a domain (the WebAuthn relying-party ID). By default Cloud OS uses the reverse proxy’s base domain when the browser is on that domain or one of its subdomains, and the exact host name otherwise. To use a different shared parent domain, set:

QUAZZAR_WEBAUTHN_RP_ID=example.com

A passkey registered at os.example.com then also works at home.example.com. Passkeys never work on bare IP addresses or on plain http://, except for localhost. See Sign-in & Lock Screen.

Reverse Proxy

Cloud OS includes a built-in Caddy reverse proxy that provides automatic HTTPS and subdomain-based routing for installed apps. When configured with a base domain like cloud.example.com, an app named “nextcloud” becomes accessible at nextcloud.cloud.example.com.

DNS requirements for automatic HTTPS:

1. A record for your base domain pointing to the server IP
2. Wildcard A record (*.cloud.example.com) pointing to the same IP
3. Ports 80 and 443 open

If you use an external reverse proxy (nginx, Traefik, Cloudflare Tunnel), disable the built-in proxy and route traffic to the Cloud OS port directly. If that proxy runs on another machine, add it to trusted_proxies (below), or every client will look like the proxy to the sign-in rate limits.

Trusted proxies

Cloud OS identifies the client of a request — for sign-in rate limits (password, 2FA, passkey, QR, approve-on-another-device, cluster join), session records and audit entries — by the TCP address the connection comes from. It believes an X-Forwarded-For / X-Real-IP header only when that connection comes from a trusted proxy; from anyone else the header is ignored, so it can’t be used to dodge rate limits or forge audit IPs.

The default trusts loopback only (127.0.0.0/8, ::1), which covers the bundled Caddy. To trust a load balancer or a proxy on another host:

server:
  trusted_proxies: ["127.0.0.0/8", "::1/128", "10.0.5.20", "172.17.0.0/16"]

or QUAZZAR_TRUSTED_PROXIES=127.0.0.0/8,::1/128,10.0.5.20. Entries are IP addresses or CIDR ranges; none trusts no proxy at all. Behind several trusted hops, the client is the right-most X-Forwarded-For entry that is not itself a trusted proxy. An invalid entry stops the service at startup.

Caddy admin unix socket

The managed Caddy process now binds its admin endpoint to a unix socket at /var/run/quazzar-caddy-admin.sock instead of 127.0.0.1:2019. This avoids a port collision with the distro caddy.service that ships with some Debian / Ubuntu variants.

On every start, Quazzar best-effort stops the distro caddy.service to reclaim ports 80 and 443. If Quazzar is offline (or crashed) when you SSH in, you can restart it safely with:

sudo systemctl restart quazzar.service

When the managed Caddy’s admin socket is missing at reload time, the service falls back to a full Stop + Start instead of returning exit status 1. If you see reload failures on older installs, upgrade to 0.6.34 or later.

sudo systemctl disable --now caddy.service
sudo systemctl mask caddy.service

Semantic search (Ollama)

The Memory MCP server uses a local Ollama instance to compute embeddings for hybrid search. Configure with:

# Ollama host URL (default: the managed Ollama container, else http://127.0.0.1:11434)
OLLAMA_HOST=http://127.0.0.1:11434
 
# Embedding model (default: nomic-embed-text, 768 dims)
MCP_EMBED_MODEL=nomic-embed-text

Pull the default model once before first use:

ollama pull nomic-embed-text

If Ollama is unreachable at boot the service logs semantic search disabled (no embedding backend) and falls back to lexical-only ranking. Every Memory MCP tool keeps working; only the cosine term of the hybrid score is dropped.

See Memory MCP for the full surface.

Memory search mode

The Memory MCP search engine supports three operating modes, controlled by:

# Values: legacy | shadow | hybrid_v2  (default: shadow)
MEMORY_SEARCH_MODE=shadow

Recommended rollout:

1. Run in shadow mode (the default) for a period that covers your typical query variety.
2. Query search_comparisons to review divergence between the two rankers:

   SELECT query, overlap_count, legacy_top_ids, v2_top_ids, created_at
   FROM search_comparisons
   ORDER BY overlap_count ASC   -- lowest overlap = biggest change
   LIMIT 20;

3. If divergence looks good (higher-quality results), flip to hybrid_v2:

   MEMORY_SEARCH_MODE=hybrid_v2
   sudo systemctl restart quazzar.service

The search_comparisons table is truncated automatically when it exceeds 10 000 rows (oldest first) to prevent unbounded growth.

Predictive Insights alerts

The Predictive Insights subsystem scores four predictors (resource anomaly, capacity forecast, backup health, app health) on an hourly cycle. Detection and on-demand serving (MCP tool, REST endpoint, dashboard card) are on by default.

Proactive push notifications — Molly alerting you without being asked, when a predictor scores high risk — are off by default and must be opted in:

# Enable proactive Molly alerts for high-risk predictions (default: false)
QUAZZAR_INSIGHTS_ALERTS=true

When enabled, the alert system respects a per-predictor dedup window: a high-risk disk-capacity alert fires at most once per hour. If the risk level is unchanged in the next scoring cycle, no duplicate notification is sent.

All four predictors can raise an alert; there is no per-predictor setting.

See Predictive Insights for a full description of the predictors and their honest-refusal behaviour.

Control Center agent listener TLS

CC_AGENT_TLS_CERT, CC_AGENT_TLS_KEY and CC_AGENT_EXTERNAL_DOMAINS are Control Center settings (in /etc/quazzar/control-center.env), not node settings. They choose the server certificate of the agent mTLS listener (CC_AGENT_ADDR, default :8443) that nodes connect to:

# Externally issued certificate + key (PEM), e.g. a wildcard for your CC domain
CC_AGENT_TLS_CERT=/var/lib/quazzar-cc/certs/server.crt
CC_AGENT_TLS_KEY=/var/lib/quazzar-cc/certs/server.key
 
# Extra DNS names for the certificate generated when no cert exists
CC_AGENT_EXTERNAL_DOMAINS=cc.example.com,agents.example.com

When the certificate file does not exist, the Control Center issues one from its own CA, covering localhost, the host’s IP addresses and the names in CC_AGENT_EXTERNAL_DOMAINS. If that path is read-only, it falls back to a temporary location and logs a warning instead of failing. See CP CA Rotation for rotating the CA itself.

Service Management

Cloud OS runs as a systemd service. Common management commands:

# Check status
sudo systemctl status quazzar.service
 
# Start / stop / restart
sudo systemctl start quazzar.service
sudo systemctl stop quazzar.service
sudo systemctl restart quazzar.service
 
# View logs
sudo journalctl -u quazzar.service -f

Database Read Replica

For high-traffic deployments, the Control Panel supports routing read-only queries to a PostgreSQL read replica.

Configuration

Set the CC_DATABASE_READ_URL environment variable to your read replica connection string:

CC_DATABASE_READ_URL="postgres://user:pass@replica-host:5432/quazzar_cc?sslmode=require"

When configured:

• Read operations (listing instances, viewing dashboards, fetching analytics) use the read replica
• Write operations (creating resources, updating settings, issuing commands) use the primary database

If CC_DATABASE_READ_URL is not set, all queries go to the primary database configured via CC_DATABASE_URL.

Control Center workflow HTTP steps

An http step of a Control Center AI workflow (AI → Workflows) is a URL written by a workspace member and fetched from inside the Control Center’s network. To stop it from reaching internal services, the Control Center refuses — after DNS resolution, and again for every redirect — any address that isn’t public: loopback (127.0.0.0/8, ::1), private (10/8, 172.16/12, 192.168/16, fc00::/7 including fd00::/8), link-local (169.254.0.0/16 — the cloud metadata address 169.254.169.254 — and fe80::/10), carrier-grade NAT (100.64.0.0/10), multicast, reserved and NAT64 / 6to4 ranges. Only http and https URLs are allowed, the step never goes through an HTTP proxy, and a name that resolves to both a public and a private address is refused. A refused step fails with destination not allowed for workflow http steps.

To let workflows call an internal receiver (a webhook relay, a self-hosted chat server…), list it in CC_WORKFLOW_HTTP_ALLOWLIST — comma-separated CIDRs, IP addresses or host names:

CC_WORKFLOW_HTTP_ALLOWLIST="10.20.0.0/16, 192.168.1.10, hooks.internal.example"

An allow-listed host name may resolve to any address; a redirect from it to another target is checked again. The allow-list is a Control Center setting on purpose, not a workspace one: on a shared Control Center a workspace must not be able to open the Control Center’s own network to itself. Restart the Control Center after changing it.

Environment variables

Every variable the node reads, grouped the same way as the packaged /etc/quazzar/quazzar.env. Set them in that file and run sudo systemctl restart quazzar. “Unset” means the feature is off or the value is derived as described. Variables marked yaml override the same setting in /etc/quazzar/quazzar.yaml.

AI and Memory kill-switches are on unless set to off, 0, false, no, disable or disabled.

Server & paths

Logging & tracing

Authentication & secrets

Reverse proxy (Caddy)

Docker & app import

Control Center & telemetry

Cluster & HA

AI (Molly)

Memory MCP

Install-time variables

These are read by the package installer (quazzar-setup) during apt install / dnf install, not by the service, so they have no effect in quazzar.env:

Control Center

The Control Center reads /etc/quazzar/control-center.env, installed by the quazzar-control-center package the same way: a commented template listing every variable below, kept on upgrade. Apply changes with sudo systemctl restart quazzar-control-center.

The template ships with these active lines: CC_ADDR=:9090, CC_DATABASE_URL=postgres://quazzar:changeme@localhost:5432/quazzar_cc?sslmode=disable, and CC_LOG_LEVEL=info. Change the Postgres password (changeme is a published placeholder) in the database and in this line. CC_JWT_SECRET is commented out: like the node, the Control Center generates a random session secret and keeps it in $CC_DATA_DIR/jwt-secret. An unset or placeholder CC_JWT_SECRET uses that file (a placeholder is logged as an error), and the package upgrade comments out an exact CC_JWT_SECRET=CHANGE_ME line. The Control Center fails closed: a value you set that is shorter than 32 characters, or a data directory it cannot read or write, stops it at start with a message naming CC_DATA_DIR and the volume to mount. Pin a value of 32+ random characters only when several Control Center replicas must share it. Changing the secret signs every Control Center user out once. The audit log’s HMAC key is CC_AUDIT_HMAC_KEY if set (32+ characters, shorter stops the Control Center), else CC_JWT_SECRET if it is strong, else a random key in $CC_DATA_DIR/audit-hmac-key. A workspace whose log was written with a placeholder key gets one audit.rekeyed entry. Which workspaces get it is fixed once, outside the database: when the Control Center creates $CC_DATA_DIR/audit-hmac-key (the first start after leaving the placeholder), or on the start with CC_AUDIT_MIGRATE_PLACEHOLDER=1, it lists the eligible workspaces with their newest entry in audit-placeholder-pending (or audit-placeholder-migrated) before writing any entry, and later starts only retry listed workspaces whose newest entry is unchanged. Verification starts at the audit.rekeyed entry and lists older entries as unverifiable. Any other mismatch, including a log re-signed with a placeholder later, is reported as tampering.

CC_ADDR, CC_LOG_LEVEL, CC_HETZNER_TOKEN and CC_DO_TOKEN are legacy and not read: the API listens on CC_API_ADDR, default :8080.

The separate billing worker binary (cmd/worker, not part of the package) also reads CC_DATABASE_URL, the three CC_STRIPE_* keys, CC_RABBITMQ_URL (default amqp://guest:guest@localhost:5672/) and CC_RABBITMQ_QUEUE_PREFIX (default quazzar_cc).

Tips

• Keep backups of /etc/quazzar/quazzar.env before making changes.
• Use journalctl -u quazzar to troubleshoot startup issues after configuration changes.
• Restart the service (sudo systemctl restart quazzar) after editing the environment file for changes to take effect.
• After an upgrade, diff /etc/quazzar/quazzar.env /etc/quazzar/quazzar.env.dpkg-dist (or .rpmnew) shows variables added since your copy was written.