Security Architecture

Details on ACT's security model, encryption, and key management.

Updated Feb 14, 2026 Edit this page

Overview

ACT (Lightweight Agent Cloud Terminal) is designed with a “security-first” architecture. Since ACT manages SSH keys and connects to your critical infrastructure, it employs industry-standard encryption and operational security practices to ensure your secrets remain safe.

Master Key (ACT_MASTER_KEY)

The cornerstone of ACT’s security is the Master Key. This is a 32-byte random key used to encrypt all sensitive data stored in the database.

  • Generation: The key is generated during the initial setup via openssl rand -base64 32 (or internal helper).
  • Storage: The key is passed to the ACT API process via the ACT_MASTER_KEY environment variable. It is never stored in the database.
  • Persistence: You (the admin) are responsible for backing up this key. If you lose the Master Key, all encrypted data (SSH keys, env vars) is irretrievably lost.
  • Verification: On startup, ACT verifies the key is valid Base64 and decodes to exactly 32 bytes.
  • The “Bus Factor” Risk: If you lose this key, there is no recovery. The database is effectively a brick. Ensure this key is stored in a secure, shared password manager (e.g., 1Password, Bitwarden) accessible to authorized team members, so that access is not lost if a single administrator leaves.

Data Encryption

ACT uses AES-256-GCM (Galois/Counter Mode) for authenticated encryption.

Algorithm Details

  • Cipher: AES-256-GCM
  • Library: Rust aes-gcm crate (audited and standard).
  • Nonce: A unique 12-byte random Nonce (Initialization Vector) is generated for every encryption operation.
  • Format: The stored format in the database is: Base64(Nonce[12] || Ciphertext).

Encrypted Fields

The following fields are always encrypted at rest:

  1. SSH Private Keys: Both Server keys (for connecting to your nodes) and Builder keys.
  2. SSH Passphrases: If your keys are password-protected.
  3. Environment Variables: All service environment variables (env_vars).
  4. Git Tokens: Personal Access Tokens for private repository cloning.
  5. Registry Passwords: Credentials for pulling images from private Docker registries.

Operational Security

Setup Token Location

During the initial installation, ACT generates a Setup Token used to create the first admin account.

  • Standard Install: The token is printed to the terminal logs.
  • File Location: If you missed the logs, you can find the token on the server at: /var/lib/act/setup_token
  • Docker: If running via Docker, check the container logs (docker logs act-api) or the mounted volume.

Ephemeral Secrets Injection

ACT avoids passing sensitive environment variables directly to processes where they might appear in ps aux or inspection tools.

How it works:

  1. When deploying a service, ACT creates a temporary, secure file on the target server containing the localized environment variables.
  2. The file is created at /var/lib/act/secrets/{uuid}.env and permission-locked (readable only by root/owner).
  3. Docker receives the variables via the --env-file argument with the temporary file mounted into the container.
  4. The temporary file is immediately deleted after the container starts.

SSH & Trust On First Use (TOFU)

ACT acts as an SSH client.

  • Key Exchange: Uses standard Ed25519 or RSA keys.
  • Host Verification: ACT implements TOFU. When you first commission a server, ACT records its SSH Host Fingerprint. Subsequent connections verify the fingerprint matches. If it changes (MITM attack or server rebuild), connection fails until you explicitly reset the fingerprint.

Webhooks

Incoming webhooks (e.g., from GitHub/GitLab) are verified using HMAC-SHA256 signatures to ensure authenticity.

Agent Security (Hardening)

The act-agent follows a strict least-privilege model. Although it must start as root to initialize eBPF programs and handle networking, it immediately drops privileges.

  • User Switch: Drops to the act user and group.
  • Capability Bounding: Retains only the minimum required Linux capabilities:
    • CAP_NET_ADMIN: To manage WireGuard interfaces.
    • CAP_BPF: To load and manage eBPF metrics programs.
    • CAP_IPC_LOCK: To lock memory for eBPF ring buffers.

This ensures that even if the agent is compromised, it cannot execute arbitrary root commands or access the host filesystem outside its scope.

  1. Secret Rotation: Rotate your ACT_MASTER_KEY periodically. Note: Key rotation requires a database migration script to re-encrypt data (currently manual).
  2. Database Security: While data is encrypted, access to the database allows attackers to corrupt or delete data. Ensure your PostgreSQL instance is firewalled.
  3. HTTPS: Always run ACT behind a reverse proxy (like built-in Traefik or Cloudflare) with HTTPS enabled.