Fnox – encrypted/remote secret manager

14 hours ago 1

Fort Knox for your secrets.

CI MIT

Secrets are done in 2 ways:

  1. In git, encrypted (hopefully)
  2. Remote, typically a cloud provider like AWS KMS

fnox works with either—or both! They've got their pros and cons. Either way, fnox gives you a nice front-end to manage secrets and make them easy to work with in dev/ci/prod.

fnox's config file, fnox.toml, will either contain the encrypted secrets, or a reference to a secret in a cloud provider. You can either use fnox exec -- <command> to run a command with the secrets, or you can use the shell integration to automatically load the secrets into your shell environment when you cd into a directory with a fnox.toml file.

fnox works with all the things:

🔐 Encryption (secrets in git, encrypted)

  • age - Modern encryption (works with SSH keys!)
  • aws-kms - AWS Key Management Service
  • azure-kms - Azure Key Vault encryption
  • gcp-kms - Google Cloud KMS

☁️ Cloud Secret Storage (remote, centralized)

  • aws-sm - AWS Secrets Manager
  • azure-sm - Azure Key Vault Secrets
  • gcp-sm - Google Cloud Secret Manager
  • vault - HashiCorp Vault
  • 1password - 1Password CLI
  • bitwarden - Bitwarden/Vaultwarden
  • keychain - OS Keychain (macOS/Windows/Linux)
  • plain - Plain text (for defaults only!)

The easiest way to install fnox is with mise:

git clone https://github.com/jdx/fnox cd fnox cargo install --path .
# Initialize fnox in your project fnox init # Set a secret (stores it encrypted in fnox.toml) fnox set DATABASE_URL # Get a secret fnox get DATABASE_URL # Run commands with secrets loaded as env vars fnox exec -- npm start # Enable shell integration (auto-load secrets on cd) eval "$(fnox activate bash)" # or zsh, fish

fnox uses a simple TOML config file (fnox.toml) that you check into git. Secrets are either:

  1. Encrypted inline - The encrypted ciphertext lives in the config file
  2. Remote references - The config contains a reference (like "my-db-password") that points to a secret in AWS/1Password/etc.

You configure providers (encryption methods or cloud services), then assign each secret to a provider. fnox handles the rest.

# fnox.toml [providers.age] type = "age" recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] [secrets.DATABASE_URL] provider = "age" value = "YWdlLWVuY3J5cHRpb24uLi4=" # ← encrypted ciphertext, safe to commit [secrets.API_KEY] default = "dev-key-12345" # ← plain default value for local dev

When you run fnox get DATABASE_URL, it decrypts the value using your age key. When you run fnox exec, all secrets are loaded as environment variables.

fnox can automatically load secrets when you cd into directories with a fnox.toml file:

# Enable it once eval "$(fnox activate bash)" # or zsh, fish # Add to your shell config for persistence echo 'eval "$(fnox activate bash)"' >> ~/.bashrc

Now secrets auto-load on directory changes:

~/projects $ cd my-app fnox: +3 DATABASE_URL, API_KEY, JWT_SECRET ~/projects/my-app $ cd .. fnox: -3 DATABASE_URL, API_KEY, JWT_SECRET

Control the output with FNOX_SHELL_OUTPUT:

  • export FNOX_SHELL_OUTPUT=none - Silent mode
  • export FNOX_SHELL_OUTPUT=normal - Show count and keys (default)
  • export FNOX_SHELL_OUTPUT=debug - Verbose debugging

Use profiles for different environments:

export FNOX_PROFILE=production cd my-app # Loads production secrets

Why is this a standalone CLI and not part of mise?

mise has support for encrypted secrets but mise's design makes it a poor fit for remote secrets. mise reloads its environment too frequently—whenever a directory is changed, mise x is run, a shim is called, etc. Any other use-case like this mise leverages caching but secrets are an area where caching is a bad idea for obvious reasons. It might be possible to change mise's design to retain its environment in part to better support something like this but that's a huge challenge.

Basically it's just too hard to get remote secrets to work effectively with mise so I made this a standalone tool.

Providers: Complete Getting Started Guides

Each provider below is a complete standalone guide. Choose the ones that fit your workflow.

Use age when: You want secrets in git, encrypted, with minimal setup. Perfect for development secrets, open source projects, or teams that want secrets in version control.

What is age? A modern encryption tool by @FiloSottile. It's simple, secure, and works beautifully with SSH keys you already have.

  1. Generate an age key (or use your existing SSH key):
# Option 1: Generate a new age key age-keygen -o ~/.config/fnox/age.txt # Option 2: Use your existing SSH key (recommended!) # age can encrypt to SSH keys directly, no conversion needed
  1. Get your public key (for encrypting secrets):
# If you generated an age key: grep "public key:" ~/.config/fnox/age.txt # Output: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p # If using SSH key: ssh-keygen -Y find-principals -s ~/.ssh/id_ed25519.pub # Or just use the SSH public key directly!
  1. Configure fnox:
fnox init # Add the age provider (use your public key) cat >> fnox.toml << 'EOF' [providers.age] type = "age" recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] # Or for SSH key: # recipients = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."] EOF
  1. Set the decryption key (your private key):
# If using age key: export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY") # If using SSH key: export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519 # Add to your shell profile for persistence: echo 'export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519' >> ~/.bashrc
# Encrypt and store a secret (automatically uses age provider) fnox set DATABASE_URL "postgresql://localhost/mydb" --provider age # The resulting fnox.toml looks like: # [secrets.DATABASE_URL] # provider = "age" # value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+I..." # ← encrypted, safe to commit! # Retrieve and decrypt fnox get DATABASE_URL # Run commands with decrypted secrets fnox exec -- npm run dev

age has first-class support for SSH keys! Instead of managing separate age keys, just use your existing SSH keys:

# Encrypt to your SSH public key [providers.age] type = "age" recipients = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs..."] # Decrypt with your SSH private key export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519

Works with ssh-ed25519 and ssh-rsa keys. For teams, add multiple recipients:

[providers.age] type = "age" recipients = [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs... # alice", "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBws... # bob", "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2el... # ci-bot" ]

Now Alice, Bob, and your CI system can all decrypt the secrets!

  1. Everyone generates/shares public keys (age or SSH)
  2. Add all public keys to recipients array in fnox.toml
  3. Commit fnox.toml to git (contains encrypted secrets)
  4. Each person sets their private key via FNOX_AGE_KEY or FNOX_AGE_KEY_FILE
  5. Everyone can decrypt secrets ✨

Pros:

  • Secrets live in git (version control, code review)
  • Works offline
  • Zero runtime dependencies
  • Free forever

Cons:

  • Key rotation requires re-encrypting all secrets
  • No audit logs
  • No centralized access control

Use 1Password when: Your team already uses 1Password, or you want a polished password manager experience with great audit logs and access control.

  1. Create a service account in 1Password:

  2. Store the token (bootstrap with age!):

# First, set up age encryption (see age section above) fnox init # ... configure age provider ... # Store the 1Password token encrypted in fnox fnox set OP_SERVICE_ACCOUNT_TOKEN "ops_YOUR_TOKEN_HERE" --provider age # Now you can bootstrap the token from fnox itself: export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN)
  1. Configure 1Password provider:
cat >> fnox.toml << 'EOF' [providers.onepass] type = "1password" vault = "Development" # Your vault name account = "my.1password.com" # Optional EOF
  1. Add secrets to 1Password (via 1Password app or CLI):
# Create an item in 1Password op item create --category=login \ --title="Database" \ --vault="Development" \ password="super-secret-password"
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "onepass" value = "Database" # ← Item name in 1Password (fetches 'password' field) [secrets.DB_USERNAME] provider = "onepass" value = "Database/username" # ← Specific field [secrets.API_KEY] provider = "onepass" value = "op://Development/API Keys/credential" # ← Full op:// URI EOF
# Export the token (one-time per session) export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN) # Get secrets from 1Password fnox get DATABASE_URL # Run commands with 1Password secrets fnox exec -- ./deploy.sh
  • "item-name" → Gets the password field
  • "item-name/field" → Gets a specific field (username, password, etc.)
  • "op://vault/item/field" → Full 1Password reference URI

Pros:

  • Beautiful UI, great mobile apps
  • Excellent audit logs and access control
  • No encryption key management
  • Team-friendly

Cons:

  • Requires 1Password subscription
  • Requires network access
  • Service account token management

Use Bitwarden when: You want an open-source password manager, or you're already using Bitwarden/Vaultwarden.

  • Bitwarden account (or self-hosted Vaultwarden)
  • Bitwarden CLI (automatically installed via mise)
  1. Login to Bitwarden:
# Login bw login # Unlock and get session token export BW_SESSION=$(bw unlock --raw)
  1. Store the session token (optional, for bootstrap):
# Store encrypted with age fnox set BW_SESSION "$(bw unlock --raw)" --provider age # Next time, bootstrap from fnox: export BW_SESSION=$(fnox get BW_SESSION)
  1. Configure Bitwarden provider:
cat >> fnox.toml << 'EOF' [providers.bitwarden] type = "bitwarden" collection = "my-collection-id" # Optional organization_id = "my-org-id" # Optional EOF
  1. Add secrets to Bitwarden (via Bitwarden app or CLI):
# Create an item bw create item --name "Database" --username "admin" --password "secret"
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "bitwarden" value = "Database" # ← Item name (fetches 'password' field) [secrets.DB_USERNAME] provider = "bitwarden" value = "Database/username" # ← Specific field EOF
# Unlock Bitwarden (once per session) export BW_SESSION=$(bw unlock --raw) # Or bootstrap: export BW_SESSION=$(fnox get BW_SESSION) # Get secrets fnox get DATABASE_URL # Run commands fnox exec -- npm start
  • "item-name" → Gets the password field
  • "item-name/field" → Gets specific field (username, password, notes, uri, totp)

For local development without a Bitwarden account:

# Start local vaultwarden server source ./test/setup-bitwarden-test.sh # Follow on-screen instructions to create account and login

Pros:

  • Open source
  • Free for personal use
  • Self-hosting option (Vaultwarden)
  • Good audit logs

Cons:

  • UI less polished than 1Password
  • Session token expires (need to unlock regularly)

Use AWS Secrets Manager when: You're running on AWS infrastructure and want centralized secret management with IAM access control, audit logs, and automatic rotation.

Note: This is remote storage - secrets live in AWS, not in your config file. Your fnox.toml only contains references to the secret names.

  • AWS account
  • AWS credentials configured (CLI, environment variables, or IAM role)
  • IAM permissions (see below)
  1. Create IAM policy for secret access:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "ListSecrets", "Effect": "Allow", "Action": "secretsmanager:ListSecrets", "Resource": "*" }, { "Sid": "ReadSecrets", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:myapp/*" } ] }
  1. Configure AWS credentials:
# Option 1: Environment variables export AWS_ACCESS_KEY_ID="AKIA..." export AWS_SECRET_ACCESS_KEY="..." export AWS_REGION="us-east-1" # Option 2: AWS CLI profile aws configure # Option 3: IAM role (if running on EC2/ECS/Lambda) # Credentials are automatic!
  1. Configure fnox provider:
cat >> fnox.toml << 'EOF' [providers.aws] type = "aws-sm" region = "us-east-1" prefix = "myapp/" # Optional: prepended to all secret names EOF
  1. Create secrets in AWS Secrets Manager:
# Via AWS CLI aws secretsmanager create-secret \ --name "myapp/database-url" \ --secret-string "postgresql://prod.db.example.com/mydb" aws secretsmanager create-secret \ --name "myapp/api-key" \ --secret-string "sk_live_abc123xyz789"
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "aws" value = "database-url" # ← With prefix, becomes "myapp/database-url" [secrets.API_KEY] provider = "aws" value = "api-key" # ← With prefix, becomes "myapp/api-key" EOF
# Secrets are fetched from AWS on-demand fnox get DATABASE_URL # Run commands (fetches all secrets from AWS) fnox exec -- ./start-server.sh # Use different profiles for different environments fnox exec --profile production -- ./deploy.sh
  • Storage: Secrets live in AWS Secrets Manager (NOT in fnox.toml)
  • Config: fnox.toml contains only the secret name/reference
  • Retrieval: Running fnox get calls AWS API to fetch the current value
  • Prefix: If configured, the prefix is prepended (e.g., value = "db-url" → fetches myapp/db-url)

Pros:

  • Centralized secret management
  • IAM access control
  • CloudTrail audit logs
  • Automatic rotation support
  • Secrets never in git

Cons:

  • Requires AWS account and network access
  • Costs money ($0.40/secret/month + $0.05/10k API calls)
  • More complex setup than encryption

Use AWS KMS when: You want secrets in git (encrypted), but with AWS-managed encryption keys and IAM access control. Different from Secrets Manager - this stores encrypted ciphertext in fnox.toml.

Note: This is local encryption - the encrypted ciphertext lives in your fnox.toml file. AWS KMS is only called to encrypt/decrypt.

  • AWS account
  • AWS credentials configured
  • KMS key created
  • IAM permissions (see below)
  1. Create KMS key:
# Via AWS CLI aws kms create-key \ --description "fnox secrets encryption" \ --key-usage ENCRYPT_DECRYPT # Note the KeyId from output

Or use AWS Console → KMS → Create Key.

  1. Create IAM policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kms:Decrypt", "kms:Encrypt", "kms:DescribeKey"], "Resource": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID" } ] }

  1. Configure AWS credentials (same as Secrets Manager above)

  2. Configure fnox provider:

cat >> fnox.toml << 'EOF' [providers.kms] type = "aws-kms" key_id = "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012" region = "us-east-1" EOF
  1. Encrypt and store secrets:
# fnox calls AWS KMS to encrypt, then stores ciphertext in config fnox set DATABASE_URL "postgresql://prod.example.com/db" --provider kms # The resulting fnox.toml contains encrypted ciphertext: # [secrets.DATABASE_URL] # provider = "kms" # value = "AQICAHhw...base64...ciphertext..." # ← Encrypted, safe to commit!
# Decrypt (calls AWS KMS) fnox get DATABASE_URL # Run commands (decrypts all secrets) fnox exec -- npm start
  1. Encryption (fnox set): Calls AWS KMS Encrypt API, stores base64 ciphertext in fnox.toml
  2. Decryption (fnox get): Calls AWS KMS Decrypt API to recover plaintext
  3. IAM Control: Access controlled via KMS key policies and IAM permissions

Pros:

  • Secrets in git (version control)
  • AWS-managed encryption keys
  • IAM access control and CloudTrail audit logs
  • No monthly per-secret charges

Cons:

  • Requires AWS account and network access
  • Costs money ($1/key/month + $0.03/10k operations)
  • More complex than age encryption

AWS KMS vs AWS Secrets Manager:

  • KMS: Encrypted secrets IN your fnox.toml (like age, but with AWS keys)
  • Secrets Manager: Secrets stored IN AWS, fnox.toml has references only

Use Azure Key Vault when: You're on Azure and want centralized secret management.

Azure provides two services: Key Vault Secrets (remote storage) and Key Vault Keys (encryption). fnox supports both.

Azure Key Vault Secrets (Remote Storage)

Use when: You want secrets stored in Azure, not in git.

  • Azure subscription
  • Key Vault created
  • Azure credentials configured
  • Permissions (see below)
  1. Create Key Vault:
# Via Azure CLI az keyvault create \ --name "myapp-vault" \ --resource-group "myapp-rg" \ --location "eastus"
  1. Assign permissions:
# Assign yourself access (for testing) az keyvault set-policy \ --name "myapp-vault" \ --upn "[email protected]" \ --secret-permissions get list # Or use RBAC (recommended): az role assignment create \ --role "Key Vault Secrets User" \ --assignee "[email protected]" \ --scope "/subscriptions/SUB-ID/resourceGroups/myapp-rg/providers/Microsoft.KeyVault/vaults/myapp-vault"
  1. Configure Azure authentication:
# Option 1: Azure CLI (for development) az login # Option 2: Service Principal (for CI/CD) export AZURE_CLIENT_ID="..." export AZURE_CLIENT_SECRET="..." export AZURE_TENANT_ID="..." # Option 3: Managed Identity (automatic on Azure VMs/Functions) # No configuration needed!
  1. Configure fnox provider:
cat >> fnox.toml << 'EOF' [providers.azure] type = "azure-sm" vault_url = "https://myapp-vault.vault.azure.net/" prefix = "myapp/" # Optional EOF
  1. Create secrets in Key Vault:
# Via Azure CLI az keyvault secret set \ --vault-name "myapp-vault" \ --name "myapp-database-url" \ --value "postgresql://prod.example.com/db"
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "azure" value = "database-url" # ← With prefix, becomes "myapp-database-url" EOF
# Fetch from Azure Key Vault fnox get DATABASE_URL # Run commands fnox exec -- ./app

Pros:

  • Centralized management
  • Azure RBAC integration
  • Audit logs
  • Managed rotation

Cons:

  • Requires Azure subscription
  • Costs money
  • Requires network access

Azure Key Vault Keys (Encryption)

Use when: You want secrets in git (encrypted), but with Azure-managed keys.

  1. Create Key Vault with key:
az keyvault key create \ --vault-name "myapp-vault" \ --name "encryption-key" \ --protection software
  1. Assign crypto permissions:
az role assignment create \ --role "Key Vault Crypto User" \ --assignee "[email protected]" \ --scope "/subscriptions/.../vaults/myapp-vault"
  1. Configure fnox:
cat >> fnox.toml << 'EOF' [providers.azurekms] type = "azure-kms" vault_url = "https://myapp-vault.vault.azure.net/" key_name = "encryption-key" EOF
  1. Encrypt secrets:
# Encrypts with Azure Key Vault, stores ciphertext in fnox.toml fnox set DATABASE_URL "secret-value" --provider azurekms

How it works: Similar to AWS KMS - ciphertext stored in config, Azure Key Vault only called for encrypt/decrypt operations.

Google Cloud Secret Manager

Use GCP Secret Manager when: You're on Google Cloud and want centralized secret management.

Like AWS, Google provides Secret Manager (remote storage) and Cloud KMS (encryption). fnox supports both.

GCP Secret Manager (Remote Storage)

Use when: You want secrets stored in GCP, not in git.

  • GCP project
  • gcloud CLI or service account
  • IAM permissions (see below)
  1. Enable Secret Manager API:
gcloud services enable secretmanager.googleapis.com
  1. Configure authentication:
# Option 1: gcloud CLI (for development) gcloud auth application-default login # Option 2: Service Account (for CI/CD) export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json" # Option 3: Workload Identity (automatic on GKE) # No configuration needed!
  1. Grant IAM permissions:
# Grant yourself access gcloud projects add-iam-policy-binding PROJECT-ID \ --member="user:[email protected]" \ --role="roles/secretmanager.secretAccessor"
  1. Configure fnox provider:
cat >> fnox.toml << 'EOF' [providers.gcp] type = "gcp-sm" project = "my-project-id" prefix = "myapp/" # Optional EOF
  1. Create secrets in Secret Manager:
# Via gcloud CLI echo -n "postgresql://prod.example.com/db" | \ gcloud secrets create myapp-database-url \ --data-file=- # Or via Console: https://console.cloud.google.com/security/secret-manager
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "gcp" value = "database-url" # ← With prefix, becomes "myapp-database-url" EOF
# Fetch from GCP fnox get DATABASE_URL # Run commands fnox exec -- ./app

Pros:

  • Integrated with GCP IAM
  • Audit logs
  • Automatic replication
  • Versioning

Cons:

  • Requires GCP project
  • Costs money
  • Requires network access

Google Cloud KMS (Encryption)

Use when: You want secrets in git (encrypted), but with GCP-managed keys.

  1. Create keyring and key:
# Enable Cloud KMS gcloud services enable cloudkms.googleapis.com # Create keyring gcloud kms keyrings create "fnox-keyring" \ --location="us-central1" # Create key gcloud kms keys create "fnox-key" \ --keyring="fnox-keyring" \ --location="us-central1" \ --purpose="encryption"
  1. Grant permissions:
gcloud kms keys add-iam-policy-binding "fnox-key" \ --keyring="fnox-keyring" \ --location="us-central1" \ --member="user:[email protected]" \ --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"
  1. Configure fnox:
cat >> fnox.toml << 'EOF' [providers.gcpkms] type = "gcp-kms" project = "my-project-id" location = "us-central1" keyring = "fnox-keyring" key = "fnox-key" EOF
  1. Encrypt secrets:
# Encrypts with GCP KMS, stores ciphertext in fnox.toml fnox set DATABASE_URL "secret-value" --provider gcpkms

How it works: Similar to AWS KMS - ciphertext in config, KMS only for encrypt/decrypt.

Use Vault when: You're already running Vault, or you need advanced features like dynamic secrets, secret leasing, or complex access policies.

  • Vault server running (self-hosted or HCP Vault)
  • Vault CLI installed: brew install vault
  • Vault token with appropriate policies
  1. Configure Vault access:
# Set Vault address export VAULT_ADDR="https://vault.example.com:8200" # Login and get token vault login -method=userpass username=myuser # Export token export VAULT_TOKEN="hvs.CAESIJ..."
  1. Create Vault policy:
# policy.hcl path "secret/data/myapp/*" { capabilities = ["read"] } path "secret/metadata/myapp/*" { capabilities = ["list"] }
vault policy write fnox-policy policy.hcl
  1. Configure fnox provider:
cat >> fnox.toml << 'EOF' [providers.vault] type = "vault" address = "https://vault.example.com:8200" path = "secret/myapp" # KV v2 mount path # token = "hvs.CAESIJ..." # Optional, can use VAULT_TOKEN env var instead EOF
  1. Store secrets in Vault:
# Via Vault CLI (KV v2 engine) vault kv put secret/myapp/database url="postgresql://prod.example.com/db" vault kv put secret/myapp/api-key value="sk_live_abc123"
  1. Reference secrets in fnox:
cat >> fnox.toml << 'EOF' [secrets.DATABASE_URL] provider = "vault" value = "database/url" # ← Vault path + field [secrets.API_KEY] provider = "vault" value = "api-key/value" EOF
# Set token (once per session, or use VAULT_TOKEN env var) export VAULT_TOKEN="hvs.CAESIJ..." # Get secrets from Vault fnox get DATABASE_URL # Run commands fnox exec -- ./app

Pros:

  • Advanced features (dynamic secrets, leasing, rotation)
  • Fine-grained access policies
  • Audit logging
  • Multi-cloud support
  • Self-hosted option

Cons:

  • Complex to set up and operate
  • Requires running Vault infrastructure
  • Token management

Use Keychain when: You want secrets stored securely on your local machine using the OS native credential store. Perfect for personal projects, local development, or storing tokens that bootstrap other providers.

fnox can store secrets in your operating system's native secure storage:

  • macOS: Keychain Access
  • Windows: Credential Manager
  • Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Secrets are stored outside fnox.toml, encrypted by the OS.

Linux only: Install libsecret:

# Ubuntu/Debian sudo apt-get install libsecret-1-0 libsecret-1-dev # Fedora/RHEL sudo dnf install libsecret libsecret-devel # Arch sudo pacman -S libsecret

All platforms:

# Configure provider cat >> fnox.toml << 'EOF' [providers.keychain] type = "keychain" service = "fnox" # Namespace for fnox secrets prefix = "myapp/" # Optional EOF
# Store a secret in OS keychain fnox set DATABASE_URL "postgresql://localhost/mydb" --provider keychain # The fnox.toml only contains a reference: # [secrets.DATABASE_URL] # provider = "keychain" # value = "database-url" # ← Keychain entry name, not the actual secret # Retrieve from keychain fnox get DATABASE_URL # Run commands fnox exec -- npm run dev
  1. Storage: Secrets stored in OS credential manager (encrypted by OS)
  2. Config: fnox.toml contains only the secret name, not the value
  3. Retrieval: fnox queries the OS keychain API
  4. Service: Acts as a namespace (isolates fnox secrets from other apps)
  5. Prefix: Additional namespacing within the service

Pros:

  • OS-managed encryption
  • Cross-platform
  • No external dependencies
  • Free

Cons:

  • Requires GUI/interactive session (doesn't work in headless CI)
  • Not suitable for teams (secrets are per-machine)
  • Keyring must be unlocked

Use case example: Store your OP_SERVICE_ACCOUNT_TOKEN in keychain, then bootstrap it for 1Password access:

[providers.keychain] type = "keychain" service = "fnox" [secrets.OP_SERVICE_ACCOUNT_TOKEN] provider = "keychain" value = "op-token"

Getting Started: A Real Example

Let's build a complete setup for a typical web app with development and production environments.

You're building an API that needs:

  • Database URL
  • API keys
  • JWT secret

Requirements:

  • Development secrets: In git, encrypted (so team can clone and run)
  • Production secrets: In AWS Secrets Manager (never in git)

This creates a fnox.toml file.

Step 2: Set Up Age Encryption (for dev secrets)

# Generate age key age-keygen -o ~/.config/fnox/age.txt # Get your public key grep "public key:" ~/.config/fnox/age.txt # age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p # Configure age provider cat >> fnox.toml << 'EOF' [providers.age] type = "age" recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] EOF # Set your private key in shell profile echo 'export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY")' >> ~/.bashrc source ~/.bashrc
# Encrypt development secrets fnox set DATABASE_URL "postgresql://localhost/mydb" --provider age fnox set JWT_SECRET "dev-jwt-secret-$(openssl rand -hex 32)" --provider age fnox set STRIPE_KEY "sk_test_abc123" --provider age

Your fnox.toml now looks like:

[providers.age] type = "age" recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] [secrets.DATABASE_URL] provider = "age" value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..." # encrypted [secrets.JWT_SECRET] provider = "age" value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..." # encrypted [secrets.STRIPE_KEY] provider = "age" value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..." # encrypted

Commit this! It's encrypted, so it's safe to push to git.

Step 4: Set Up Production (AWS Secrets Manager)

# Add production profile cat >> fnox.toml << 'EOF' [profiles.production] [profiles.production.providers.aws] type = "aws-sm" region = "us-east-1" prefix = "myapi/" [profiles.production.secrets.DATABASE_URL] provider = "aws" value = "database-url" [profiles.production.secrets.JWT_SECRET] provider = "aws" value = "jwt-secret" [profiles.production.secrets.STRIPE_KEY] provider = "aws" value = "stripe-key" EOF

Now create the secrets in AWS:

aws secretsmanager create-secret \ --name "myapi/database-url" \ --secret-string "postgresql://prod.rds.amazonaws.com/mydb" aws secretsmanager create-secret \ --name "myapi/jwt-secret" \ --secret-string "$(openssl rand -base64 64)" aws secretsmanager create-secret \ --name "myapi/stripe-key" \ --secret-string "sk_live_REAL_KEY_HERE"

Development:

# Enable shell integration (one time) eval "$(fnox activate bash)" echo 'eval "$(fnox activate bash)"' >> ~/.bashrc # Now just cd into the project cd my-api # fnox: +3 DATABASE_URL, JWT_SECRET, STRIPE_KEY # Run your app (secrets are already loaded!) npm run dev # Or explicitly: fnox exec -- npm run dev

Production:

# Set AWS credentials (IAM role, or env vars) export AWS_REGION=us-east-1 # Run with production profile fnox exec --profile production -- node server.js

CI/CD:

# .github/workflows/deploy.yml name: Deploy on: [push] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: jdx/mise-action@v3 # you'll need a mise.toml with fnox configured - name: Setup age key env: FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }} run: | mkdir -p ~/.config/fnox echo "$FNOX_AGE_KEY" > ~/.config/fnox/age.txt chmod 600 ~/.config/fnox/age.txt - name: Deploy to production env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} run: | fnox exec --profile production -- ./deploy.sh
  1. ✅ Dev secrets are encrypted in git → Team can clone and run immediately
  2. ✅ Prod secrets are in AWS → Never in git, centrally managed
  3. ✅ Shell integration → Secrets auto-load on cd
  4. ✅ CI/CD ready → GitHub Actions can decrypt dev secrets and access AWS for prod
  5. ✅ Profiles → Same fnox.toml, different environments

Organize secrets by environment:

# Default profile (dev) [secrets.API_URL] default = "http://localhost:3000" # Staging profile [profiles.staging.secrets.API_URL] default = "https://staging.example.com" # Production profile [profiles.production.secrets.API_URL] provider = "aws" value = "api-url"
fnox get API_URL # dev fnox get API_URL --profile staging # staging fnox get API_URL --profile production # production

Hierarchical Configuration

fnox searches parent directories for fnox.toml files and merges them:

project/ ├── fnox.toml # Root: age encryption, common secrets └── services/ └── api/ └── fnox.toml # API-specific secrets, inherits age config

Child configs override parent values. Great for monorepos!

Split configs across files:

# fnox.toml imports = ["./secrets/dev.toml", "./secrets/prod.toml"] [providers.age] type = "age" recipients = ["age1..."]
# secrets/dev.toml [secrets.DATABASE_URL] provider = "age" value = "encrypted..."

fnox resolves secrets in this order:

  1. Encrypted value (provider = "age", value = "encrypted...")
  2. Provider reference (provider = "aws", value = "secret-name")
  3. Environment variable (if $ENV_VAR exists)
  4. Default value (default = "fallback")

First match wins!

Set fallbacks for optional secrets:

[secrets.NODE_ENV] default = "development" # Used if not found elsewhere [secrets.LOG_LEVEL] default = "info" if_missing = "warn" # "error", "warn", or "ignore"

Migrate from .env files:

# Import from .env fnox import --format env --source .env # Export to various formats fnox export --format json > secrets.json fnox export --format yaml > secrets.yaml fnox export --format toml > secrets.toml
  • fnox init - Initialize fnox.toml
  • fnox get <KEY> - Get a secret value
  • fnox set <KEY> [VALUE] - Set a secret (encrypts if provider supports it)
  • fnox list - List all secrets
  • fnox remove <KEY> - Remove a secret
  • fnox exec -- <COMMAND> - Run command with secrets as env vars
  • fnox export - Export secrets in various formats
  • fnox import - Import secrets from files
  • fnox provider list - List all providers
  • fnox provider test <NAME> - Test provider connection
  • fnox profiles - List all profiles
  • fnox edit - Open config in editor
  • fnox doctor - Show diagnostic info
  • fnox check - Verify all secrets are configured
  • fnox scan - Scan for plaintext secrets in code
  • fnox activate <SHELL> - Generate shell activation code
  • fnox hook-env - Internal command for shell hooks
  • fnox completion <SHELL> - Generate completions
  • fnox ci-redact - Mask secrets in CI logs
  • FNOX_PROFILE - Active profile (default: default)
  • FNOX_CONFIG_DIR - Config directory (default: ~/.config/fnox)
  • FNOX_AGE_KEY - Age encryption key (alternative to file)
  • FNOX_AGE_KEY_FILE - Path to age key file
  • FNOX_SHELL_OUTPUT - Shell integration output (none, normal, debug)
Read Entire Article
  1. Homepage
  2. Technology
  3. Fnox – encrypted/remote secret manager

Related

Sustained growth through creative destruction: Nobel laureates Philippe Aghion

Sustained growth through creative destruction: Nobel laureat...

13 minutes ago 0
Congratulations, Publicly

Congratulations, Publicly

14 minutes ago 0
Halo's 25th anniversary brings game to PlayStation

Halo's 25th anniversary brings game to PlayStation

16 minutes ago 0
Hostinger Web Hosting