Architecture & Security

How envv actually works, and why your secrets are safer than SaaS alternatives.

The Core Principle

We store your secrets so teammates can sync them — but we can't read them.

envv uses end-to-end encryption where all encryption and decryption happens on your machine. Secrets are encrypted with your team's public keys before being pushed to our servers. Only team members with private keys can decrypt. Our servers store ciphertext we can't use.

Built on Battle-Tested Technology

envv is built on Mozilla SOPS (Secrets OPerationS), which has been used in production by thousands of companies since 2015. We're not reinventing cryptography - we're adding team collaboration to a proven foundation.

Foundation

Encryption: AES-256-GCM (NIST-approved AEAD cipher)
Key format: Modern age keys (simpler than PGP, auditable)
CLI: Built on SOPS - battle-tested since 2015
Backend: Handles team coordination, never sees secret values

We're still iterating on the backend architecture. Working with design partners to figure out what actually matters for 3-10 person teams.

How Encryption Works

When You Push Secrets

1. You Run
envv push .env --env prod

→

2. CLI Encrypts
AES-256-GCM locally

→

3. Uploads
Ciphertext to backend

What gets encrypted (stored in .envv/ and backend):

{
    "KEY": "ENC[AES256_GCM,data:vL8t...,iv:Hg==,tag:zA==,type:str]",
    "sops": {
        "age": [
            {
                "recipient": "age1ql3z7hjy54pw3h...",
                "enc": "-----BEGIN AGE..."
            }
        ],
        "mac": "ENC[AES256_GCM,data:3kL...]"
    }
}
            

What's happening:

✓ Secret value is encrypted with AES-256-GCM
✓ Data key is encrypted with your team's age public keys
✓ MAC ensures file integrity (detects tampering)
✓ Zero plaintext on disk

When You Run Your App

1. You Run
envv run -- npm start

→

2. CLI Decrypts
In memory only

→

3. Injects + Runs
Zero plaintext on disk

Team Management Architecture

The Trust Model

The backend's job: store encrypted secrets and manage team membership.

Secrets are encrypted on your machine before upload. Your private keys stay on your laptop. The backend stores ciphertext it can't decrypt and tracks which public keys belong to which projects.

What the Backend Knows

Information	Stored?	Why
User email	✓ Yes	Account management
Team membership	✓ Yes	Access control
Public keys (age/PGP)	✓ Yes	Enable encryption for team
Audit logs (who, when)	✓ Yes	Compliance and security
Encrypted secrets	✓ Yes	Stored so teammates can sync (but we can't decrypt)
Plaintext secret values	✗ No	Never sent to our servers
Private keys	✗ No	Generated and stored locally

Team Workflow

Scenario: Alice wants to give Bob access to team secrets

# 1. Alice invites Bob
$ envv org invite --email=bob@acme.com

# What happens:
# - Backend emails Bob an invite link
# - Bob registers and generates age keypair LOCALLY
# - Bob uploads ONLY his public key to backend

# 2. Bob joins and pulls secrets
$ git clone repo && cd repo
$ envv project init --org-id=org_xxx --project-id=proj_xxx
$ envv pull --env production

# What happens:
# - Encrypted secrets cached in .envv/
# - Bob can decrypt (has private key)

# 3. Alice updates secrets
$ envv push .env --env production

# What happens:
# - CLI encrypts for ALL team member public keys
# - Uploads ciphertext to backend
# - Bob runs `envv run` and gets new secrets
            

Security Properties

End-to-End Encryption

Secrets are encrypted on your machine and can only be decrypted by team members with private keys. The backend cannot decrypt your secrets even if compromised.

End-to-End Encrypted

We store encrypted secrets so your team can sync them, but we can't decrypt them. We know who's on your team and when they accessed the system — but we can't read any secret values, even if we wanted to.

Offline-First

Your app continues to work even if:

Our backend is down
You're on an airplane
Your VPN is disconnected
We go out of business

Encryption and decryption happen entirely locally. Backend is only needed for team management.

Auditable

Unlike SaaS secret managers where you trust their claims:

✓ Our code is open source (fork of Mozilla SOPS)
✓ Encryption happens client-side (you can verify)
✓ Encrypted files are in your git (you control them)

Threat Model

What We Protect Against

Threat	Protection
Laptop stolen	Secrets encrypted at rest, private key is passphrase-protected
Git repo leaked	Secrets are encrypted, useless without private keys
Backend compromised	Only encrypted secrets stored, attackers get ciphertext they can't decrypt
Insider threat	Audit logs track all access, remove team member = re-encrypt
Supply chain attack	Builds are reproducible, binary is signed, code is open source

What We Don't Protect Against

Be honest about limitations:

Malware on your laptop (could steal private key or memory)
Social engineering (could trick you into revealing secrets)
Quantum computers (AES-256 is quantum-resistant for now)
$5 wrench attack (XKCD 538)

Comparison to Alternatives

vs HashiCorp Vault

Vault: Centralized secret storage, requires server running 24/7

envv: Decentralized (git), works offline, no server required

vs AWS Secrets Manager

AWS: Cloud-hosted, requires internet, AWS lock-in

envv: Local-first, works offline, cloud KMS optional

vs 1Password Teams

1Password: Great for humans, not designed for CI/CD

envv: CLI-first, designed for developers and automation

vs Plain SOPS

SOPS: Manual key management, no team features

envv: Automated team management, audit logs, rotation

Compliance

envv's architecture makes compliance easier:

SOC 2: Audit logs track all access
GDPR: No PII in secrets, data stays in your region
HIPAA: Encryption at rest and in transit
PCI-DSS: Secrets never stored unencrypted

Enterprise plan includes compliance documentation and support.

Questions?

Security Concerns?

We take security seriously. If you've found a vulnerability, please report it via GitHub Security Advisories.

For general architecture questions: GitHub Discussions

Documentation Request Access