Master Key Management

The Master Key (SERVOS_MASTER_KEY) is the most critical secret in your ServOS installation. It is a 32-byte hexadecimal key used to encrypt all sensitive data in the database, including:

• SSH Private Keys
• Environment Variables
• Git Access Tokens
• Database Passwords

Security & Storage

• Storage: The key is typically stored in /etc/servos/servos.env (for automated installs) or injected via the SERVOS_MASTER_KEY environment variable.
• Protection: Ensure file permissions are set to 600 (read/write by owner only) for any file containing the key.

Docker Secrets

For containerized deployments (Docker Swarm/Kubernetes), you can use the SERVOS_MASTER_KEY_FILE environment variable to point to a file containing the key. This prevents exposing the key in environment variables.

# docker-compose.yml example
services:
  servos:
    image: actplatform/servos
    environment:
      SERVOS_MASTER_KEY_FILE: /run/secrets/servos_master_key
    secrets:
      - servos_master_key

secrets:
  servos_master_key:
    file: ./servos_master_key.txt

[!CAUTION] Data Loss Risk: If you lose your Master Key, all encrypted data in your database becomes permanently unrecoverable. You will lose access to your servers and secrets.

Integrity Canary

ServOS implements an Integrity Canary mechanism to prevent data corruption.

1. On first boot, ServOS encrypts a known “canary” value using the current Master Key and stores it in the database.
2. On every subsequent startup, ServOS attempts to decrypt this canary.
3. If decryption fails (because the provided Master Key is different), ServOS refuses to start.

This prevents the system from booting with the wrong key and potentially writing new data that acts as “double-encrypted” garbage or corrupting existing records.

If you see “MASTER KEY INTEGRITY CHECK FAILED” in logs:

• You are likely using the wrong Master Key.
• Check your servos.env or environment variables against your backups.

Key Rotation

Rotating the Master Key is a sensitive operation that involves re-encrypting all secrets in the database.

[!WARNING] Backup Required: Always perform a full database backup (servos.db or SQL dump) before attempting key rotation.

Rotation Process

1. Generate New Key: create a new 32-byte hex string.
2. Trigger Rotation (via API): Call the POST /api/v1/system/rotate-master-key endpoint with the new key. ServOS will:
   • Decrypt all data with the old key.
   • Re-encrypt all data with the new key.
   • Update the Integrity Canary.
3. Update Configuration: Update your SERVOS_MASTER_KEY environment variable on the server.
4. Restart: Restart the ServOS service.

[Start Rotation] ──► [Generate New Key]
                            │
                            ▼
[API: /rotate] ──► [Decrypt with Old Key] ──► [Encrypt with New Key]
                            │
                            ▼
                    [Update Canary]
                            │
                            ▼
[Manual Step] ──► [Update Env Var] ──► [Restart ServOS]