Master Key Management

Updated Jan 21, 2026 Edit this page

Master Key Management

The Master Key (ACT_MASTER_KEY) is the most critical secret in your ACT 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/act/act.env (for automated installs) or injected via the ACT_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 ACT_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:
  act:
    image: actplatform/act
    environment:
      ACT_MASTER_KEY_FILE: /run/secrets/act_master_key
    secrets:
      - act_master_key

secrets:
  act_master_key:
    file: ./act_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

ACT implements an Integrity Canary mechanism to prevent data corruption.

  1. On first boot, ACT encrypts a known “canary” value using the current Master Key and stores it in the database.
  2. On every subsequent startup, ACT attempts to decrypt this canary.
  3. If decryption fails (because the provided Master Key is different), ACT 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 act.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 (act.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. ACT 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 ACT_MASTER_KEY environment variable on the server.
  4. Restart: Restart the ACT service.
[Start Rotation] ──► [Generate New Key]
                            │
                            ▼
[API: /rotate] ──► [Decrypt with Old Key] ──► [Encrypt with New Key]
                            │
                            ▼
                    [Update Canary]
                            │
                            ▼
[Manual Step] ──► [Update Env Var] ──► [Restart ACT]