Security Architecture

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

Updated Jan 21, 2026 Edit this page

Overview

ACT (Agentless 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.

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

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 permission-locked (readable only by root/owner).
  3. Docker receives the variables via the --env-file argument or equivalent injection method.
  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.

  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.