Installation

# One-liner (recommended)
curl -fsSL https://raw.githubusercontent.com/forattini-dev/vaulter/main/install.sh | sh

# Or via npm/pnpm
npm install -g vaulter
pnpm add -g vaulter

Quick Start

# Initialize project
vaulter init

# Set secrets (encrypted, synced to backend)
vaulter set DATABASE_URL="postgres://localhost/mydb" -e dev

# Export to shell
eval $(vaulter export -e dev)

# Deploy to Kubernetes
vaulter k8s:secret -e prd | kubectl apply -f -

Table of Contents

• Why Vaulter?
• Security
• Daily Use
• CI/CD
• Configuration
• Integrations
• Monorepo Support
• API Usage
• MCP Server

Why Vaulter?

The Problem

Environment variables and secrets are scattered across .env files, CI/CD settings, cloud consoles, and team Slack messages. This creates:

• Security gaps: Secrets in plaintext files, git history, or shared docs
• Sync issues: "Works on my machine" because .env files differ
• Deploy friction: Manual copy-paste between environments
• Audit blindness: No idea who changed what, when

The Solution

Vaulter centralizes all environment variables in encrypted storage (S3-compatible) while maintaining the simplicity of .env files:

Why Trust Vaulter?

1. Open source: All code is auditable
2. No lock-in: Your data lives in YOUR storage (S3, MinIO, R2, filesystem)
3. Standard encryption: AES-256-GCM, the same used by AWS, Google, and banks
4. Zero external dependencies: No SaaS, no API keys, no third-party services
5. Offline capable: Works with local filesystem backend

Security

Encryption Model

Every secret is encrypted before leaving your machine using AES-256-GCM:

┌─────────────────────────────────────────────────────────────┐
│                     Your Machine                            │
│                                                             │
│  .env file ──► vaulter encrypt ──► encrypted blob ──► S3   │
│               (AES-256-GCM)         (unreadable)           │
│                                                             │
│  S3 ──► encrypted blob ──► vaulter decrypt ──► .env file   │
│         (unreadable)       (AES-256-GCM)                   │
└─────────────────────────────────────────────────────────────┘

What this means:

• The backend (S3, MinIO, etc.) only sees encrypted data
• Even with S3 access, secrets are unreadable without the key
• Each value is encrypted individually (field-level encryption)
• Authenticated encryption prevents tampering (GCM mode)

Key Management

Vaulter stores keys in ~/.vaulter/ directory (outside project) for security:

~/.vaulter/
├── projects/
│   └── <project-name>/
│       └── keys/
│           ├── master           # Private key (mode 600)
│           └── master.pub       # Public key (mode 644)
└── global/
    └── keys/                    # Shared across all projects
        ├── shared
        └── shared.pub

Key Commands

# Generate keys
vaulter key generate --name master                    # Symmetric key
vaulter key generate --name master --asymmetric       # RSA-4096 key pair
vaulter key generate --name master --asym --alg ec-p256  # EC P-256 key pair
vaulter key generate --name shared --global           # Global key (all projects)

# List and show keys
vaulter key list                      # List all keys (project + global)
vaulter key show --name master        # Show key details

# Export/import for deployment
vaulter key export --name master -o keys.enc    # Export encrypted bundle
vaulter key import -f keys.enc                  # Import on another machine

# Set VAULTER_EXPORT_PASSPHRASE to encrypt the bundle with custom passphrase

Configuration with key_name

The simplest way to use keys is via key_name resolution:

# .vaulter/config.yaml
encryption:
  mode: asymmetric
  asymmetric:
    algorithm: rsa-4096
    key_name: master           # → ~/.vaulter/projects/<project>/keys/master[.pub]
    # Or for global key:
    # key_name: global:master  # → ~/.vaulter/global/keys/master[.pub]

Legacy Key Sources (still supported)

You can also specify explicit key sources:

encryption:
  key_source:
    - env: VAULTER_KEY           # 1. Environment variable (CI/CD)
    - file: .vaulter/.key        # 2. Local file (development)
    - s3: s3://keys/vaulter.key  # 3. Remote S3 (shared teams)

Option 1: Environment Variable (Recommended for CI/CD)

# Generate a key
vaulter key generate --name master

# Set in CI/CD secrets from the generated key
export VAULTER_KEY=$(cat ~/.vaulter/projects/myproject/keys/master)

Pros: Key never in project directory, rotates easily via CI/CD secret rotation Use case: GitHub Actions, GitLab CI, Jenkins

Option 2: key_name Resolution (Recommended for Development)

encryption:
  mode: asymmetric
  asymmetric:
    key_name: master    # Auto-resolves to ~/.vaulter/projects/<project>/keys/

Pros: Simple, keys stored securely outside project Use case: Local development, team workflows

Option 3: Remote S3 (Team Shared)

encryption:
  key_source:
    - s3: s3://company-keys/vaulter/project.key?region=us-east-1

Pros: Centralized key management, IAM-controlled access Use case: Teams, multiple developers needing same key

Asymmetric Key Encryption (RSA/EC)

For enhanced security with separate encrypt/decrypt permissions, Vaulter supports hybrid encryption using RSA or Elliptic Curve key pairs.

How It Works

┌────────────────────────────────────────────────────────────────┐
│                     Hybrid Encryption                          │
│                                                                │
│  Your secret ──► AES-256-GCM ──► Encrypted data               │
│                      │                                         │
│                      │ (random AES key)                        │
│                      ▼                                         │
│  Public key ──► RSA/EC encrypt ──► Encrypted AES key          │
│                                                                │
│  Stored: { encrypted_key + encrypted_data + metadata }        │
│                                                                │
│  Decryption requires: Private key + Encrypted blob            │
└────────────────────────────────────────────────────────────────┘

Benefits:

• Separation of duties: Public key can only encrypt, private key can decrypt
• CI/CD security: Give CI/CD only the public key - it can write but not read secrets
• Production isolation: Only production has the private key for decryption

Generate Key Pair

# RSA 4096-bit (default, most compatible)
vaulter key generate --name master --asymmetric

# RSA 2048-bit (faster, less secure)
vaulter key generate --name master --asym --algorithm rsa-2048

# Elliptic Curve P-256 (modern, fast)
vaulter key generate --name master --asym --alg ec-p256

# Elliptic Curve P-384 (stronger EC)
vaulter key generate --name master --asym --alg ec-p384

# Global key (shared across all projects)
vaulter key generate --name shared --global --asymmetric

Output:

✓ Generated rsa-4096 key pair: master
  Private: ~/.vaulter/projects/my-project/keys/master (mode 600 - keep secret!)
  Public:  ~/.vaulter/projects/my-project/keys/master.pub (mode 644)

To use these keys in config.yaml:
  encryption:
    mode: asymmetric
    asymmetric:
      algorithm: rsa-4096
      key_name: master

Configuration

# .vaulter/config.yaml
encryption:
  mode: asymmetric              # Enable asymmetric mode
  asymmetric:
    algorithm: rsa-4096         # or rsa-2048, ec-p256, ec-p384
    key_name: master            # Uses ~/.vaulter/projects/<project>/keys/master[.pub]
    # Or for global keys:
    # key_name: global:master   # Uses ~/.vaulter/global/keys/master[.pub]

# Alternative: explicit key sources (for CI/CD or custom paths)
# encryption:
#   mode: asymmetric
#   asymmetric:
#     algorithm: rsa-4096
#     public_key:
#       - file: /path/to/master.pub
#       - env: VAULTER_PUBLIC_KEY
#     private_key:
#       - file: /path/to/master
#       - env: VAULTER_PRIVATE_KEY

Supported Algorithms

Use Case: Secure CI/CD Pipeline

┌─────────────────────────────────────────────────────────────┐
│ Development                                                  │
│   Developers have BOTH keys → can read and write secrets    │
│   vaulter set API_KEY="..." -e dev                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ CI/CD (GitHub Actions, Jenkins, etc.)                        │
│   Only PUBLIC key → can write NEW secrets, cannot read      │
│   Useful for automated secret rotation scripts              │
│                                                             │
│   env:                                                      │
│     VAULTER_PUBLIC_KEY: ${{ secrets.VAULTER_PUBLIC_KEY }}   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ Production                                                   │
│   Only PRIVATE key → can read secrets at runtime            │
│                                                             │
│   env:                                                      │
│     VAULTER_PRIVATE_KEY: ${{ secrets.VAULTER_PRIVATE_KEY }} │
│                                                             │
│   # Application reads secrets at startup                    │
│   eval $(vaulter export -e prd)                             │
└─────────────────────────────────────────────────────────────┘

Environment Variables

Advanced Security Configurations

AWS KMS Integration (Planned)

For enterprises requiring HSM-backed keys:

encryption:
  kms:
    key_id: arn:aws:kms:us-east-1:123456789:key/abc-123
    # Key never leaves AWS KMS
    # Envelope encryption: KMS encrypts the data key

How it works:

1. Vaulter generates a data encryption key (DEK)
2. DEK encrypts your secrets locally
3. AWS KMS encrypts the DEK (envelope encryption)
4. Only encrypted DEK + encrypted secrets are stored
5. Decryption requires both KMS access AND S3 access

Threat Model

Security Best Practices

# ✅ DO
vaulter key generate                    # Random 256-bit key
echo ".vaulter/.key" >> .gitignore      # Never commit keys
export VAULTER_KEY="${{ secrets.KEY }}" # CI/CD secrets

# ❌ DON'T
echo "password123" > .vaulter/.key      # Weak key
git add .vaulter/.key                   # Exposed key
vaulter set KEY=val --key "hardcoded"   # Key in command history

Daily Use

Workflow Overview

# Morning: sync with team's changes
vaulter pull -e dev

# During development: add new variable
vaulter set NEW_API_KEY="sk-xxx" -e dev

# End of day: push changes
vaulter push -e dev

# Deploy: export to production
vaulter k8s:secret -e prd | kubectl apply -f -

Commands Reference

Core Commands

Sync Commands

Integration Commands

Set Command Syntax

# Secrets (encrypted, synced to backend)
vaulter set KEY=value                    # Single secret
vaulter set A=1 B=2 C=3 -e dev           # Batch secrets
vaulter set KEY:=123                     # Typed (number/boolean)

# Configs (plain text in split mode)
vaulter set PORT::3000 HOST::localhost   # Configs

Global Options

-p, --project <name>    Project name
-s, --service <name>    Service name (monorepos)
-e, --env <env>         Environment name (as defined in config)
-b, --backend <url>     Backend URL override
-k, --key <path|value>  Encryption key
-f, --file <path>       Input file path
-o, --output <path>     Output file path
-n, --namespace <name>  Kubernetes namespace
    --format <fmt>      Output format (shell/json/yaml/env/tfvars/docker-args)
-v, --verbose           Verbose output (shows values)
    --dry-run           Preview without applying
    --json              JSON output
    --force             Skip confirmations
    --all               Apply to all services in monorepo

Flexible Environment Names

Vaulter lets you define your own environment names. Use whatever convention fits your workflow:

# Short names (default)
environments: [dev, stg, prd]

# Full names
environments: [development, staging, production]

# Custom names
environments: [local, homolog, qa, uat, prod]

# Brazilian pattern
environments: [dev, homolog, prd]

All commands use -e with your custom names:

vaulter list -e homolog
vaulter pull -e development
vaulter k8s:secret -e uat | kubectl apply -f -

CI/CD

GitHub Actions (Quick Start)

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy secrets to Kubernetes
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          npx vaulter k8s:secret -e prd | kubectl apply -f -

GitHub Actions (Complete Example)

name: Deploy to Kubernetes
on:
  push:
    branches: [main, develop]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'dev'
        type: choice
        options: [dev, stg, prd]

env:
  VAULTER_VERSION: '1.0.1'

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'prd') || 'dev' }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install Vaulter
        run: npm install -g vaulter@${{ env.VAULTER_VERSION }}

      - name: Configure kubectl
        uses: azure/k8s-set-context@v4
        with:
          kubeconfig: ${{ secrets.KUBECONFIG }}

      - name: Deploy Secrets
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          ENV=${{ github.event.inputs.environment || (github.ref == 'refs/heads/main' && 'prd') || 'dev' }}

          # Deploy K8s Secret
          vaulter k8s:secret -e $ENV -n my-namespace | kubectl apply -f -

          # Deploy ConfigMap (non-sensitive config)
          vaulter k8s:configmap -e $ENV -n my-namespace | kubectl apply -f -

          # Verify deployment
          kubectl get secret,configmap -n my-namespace

      - name: Restart Deployment
        run: |
          kubectl rollout restart deployment/my-app -n my-namespace
          kubectl rollout status deployment/my-app -n my-namespace --timeout=120s

GitHub Actions (Monorepo with Services)

name: Deploy Service
on:
  push:
    branches: [main]
    paths:
      - 'apps/svc-*/**'

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.changes.outputs.services }}
    steps:
      - uses: actions/checkout@v4
      - id: changes
        run: |
          # Detect which services changed
          SERVICES=$(git diff --name-only HEAD~1 | grep '^apps/svc-' | cut -d'/' -f2 | sort -u | jq -R -s -c 'split("\n")[:-1]')
          echo "services=$SERVICES" >> $GITHUB_OUTPUT

  deploy:
    needs: detect-changes
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: ${{ fromJson(needs.detect-changes.outputs.services) }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy ${{ matrix.service }}
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          # Deploy secrets for specific service
          vaulter k8s:secret -e prd -s ${{ matrix.service }} | kubectl apply -f -

GitHub Actions (Using Binary for Speed)

name: Deploy (Fast)
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Vaulter Binary
        run: |
          curl -sL https://github.com/forattini-dev/vaulter/releases/latest/download/vaulter-linux -o vaulter
          chmod +x vaulter
          sudo mv vaulter /usr/local/bin/

      - name: Deploy
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          vaulter k8s:secret -e prd | kubectl apply -f -

GitHub Actions (Matrix Deploy)

name: Deploy All Environments
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, stg, prd]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - name: Deploy secrets
        env:
          VAULTER_KEY: ${{ secrets.VAULTER_KEY }}
        run: |
          npx vaulter k8s:secret -e ${{ inputs.environment }} | kubectl apply -f -

      - name: Deploy configmaps
        run: |
          npx vaulter k8s:configmap -e ${{ inputs.environment }} | kubectl apply -f -

GitLab CI

stages:
  - deploy

deploy-secrets:
  stage: deploy
  image: node:22-alpine
  script:
    - npx vaulter k8s:secret -e ${CI_ENVIRONMENT_NAME} | kubectl apply -f -
  environment:
    name: $CI_COMMIT_REF_NAME
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      variables:
        CI_ENVIRONMENT_NAME: prd
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        CI_ENVIRONMENT_NAME: dev

Jenkins Pipeline

pipeline {
    agent any

    environment {
        VAULTER_KEY = credentials('vaulter-key')
        AWS_ACCESS_KEY_ID = credentials('aws-access-key')
        AWS_SECRET_ACCESS_KEY = credentials('aws-secret-key')
    }

    stages {
        stage('Deploy Secrets') {
            steps {
                sh 'npx vaulter k8s:secret -e prd | kubectl apply -f -'
            }
        }
    }
}

Docker Integration

# Recommended: Use --env-file for production (handles all values safely)
vaulter export -e prd --format=env > .env.prd
docker run --env-file .env.prd myapp

# For simple values only: command substitution (no spaces/newlines in values)
docker run $(vaulter export -e prd --format=docker-args) myapp

Note: The docker-args format outputs -e "KEY=VALUE" flags. Due to shell word-splitting, values containing spaces or special characters won't work correctly with $(...) substitution. Use --env-file for complex values or production deployments.

For docker build with build args, use shell format:

# Export to shell and use in build
eval $(vaulter export -e prd)
docker build \
  --build-arg DATABASE_URL="$DATABASE_URL" \
  --build-arg API_KEY="$API_KEY" \
  -t myapp .

Terraform Integration

# Generate tfvars
vaulter tf:vars -e prd > secrets.auto.tfvars

# Or inline
terraform plan -var-file=<(vaulter tf:vars -e prd)

Helm Integration

# Upgrade with secrets as values
vaulter helm:values -e prd | helm upgrade myapp ./chart -f -

# Or save to file
vaulter helm:values -e prd > values.secrets.yaml
helm upgrade myapp ./chart -f values.yaml -f values.secrets.yaml

Shell Aliases (Development)

# Add to ~/.bashrc or ~/.zshrc
alias vdev='eval $(vaulter export -e dev)'
alias vstg='eval $(vaulter export -e stg)'
alias vprd='eval $(vaulter export -e prd)'

# Usage
vdev npm run dev
vstg npm run test:integration

Configuration

Basic Config

# .vaulter/config.yaml
version: "1"

project: my-project
service: api  # optional, for monorepos

backend:
  url: s3://bucket/envs?region=us-east-1
  # Or multiple with fallback
  urls:
    - s3://bucket/envs?region=us-east-1
    - file:///home/user/.vaulter-store

encryption:
  key_source:
    - env: VAULTER_KEY
    - file: .vaulter/.key

environments:
  - dev
  - stg
  - prd

default_environment: dev

Directory Modes

Unified Mode (Default)

my-project/
├── .vaulter/
│   ├── config.yaml
│   └── environments/
│       ├── dev.env
│       ├── stg.env
│       └── prd.env

Split Mode

Separates configs (committable) from secrets (gitignored):

my-project/
├── .vaulter/config.yaml
└── deploy/
    ├── configs/           # ✅ Committable (PORT, HOST, LOG_LEVEL)
    │   ├── dev.env
    │   └── prd.env
    └── secrets/           # ❌ Gitignored (DATABASE_URL, API_KEY)
        ├── dev.env
        └── prd.env

directories:
  mode: split
  configs: deploy/configs
  secrets: deploy/secrets

Initialize with: vaulter init --split

Backend URLs

Integrations

Kubernetes

# Deploy Secret
vaulter k8s:secret -e prd -n my-namespace | kubectl apply -f -

# Deploy ConfigMap
vaulter k8s:configmap -e prd | kubectl apply -f -

Note: Custom secret/configmap names are configured in .vaulter/config.yaml:

integrations:
  kubernetes:
    secret_name: my-app-secrets
    configmap_name: my-app-config

Helm

# Pass as values
vaulter helm:values -e prd | helm upgrade myapp ./chart -f -

# Save to file
vaulter helm:values -e prd > values.secrets.yaml

Terraform

# Generate tfvars
vaulter tf:vars -e prd > terraform.tfvars

# Generate JSON
vaulter tf:json -e prd > terraform.tfvars.json

Monorepo Support

Vaulter auto-detects all major monorepo tools:

Scan Command

# Discover all packages
vaulter scan

# Output:
# Monorepo: NX
# Found 17 package(s):
#   ✓ Initialized: 3
#   ○ Not initialized: 14
#   📄 With .env files: 11

Batch Operations

# Sync all services
vaulter sync -e dev --all

# Sync specific services
vaulter sync -e dev -s api,worker

API Usage

import { VaulterClient, loadConfig } from 'vaulter'

const config = loadConfig()
const client = new VaulterClient({ config })

await client.connect()

// CRUD operations
const value = await client.get('DATABASE_URL', 'my-project', 'prd')
await client.set({ key: 'API_KEY', value: 'sk-xxx', project: 'my-project', environment: 'prd' })
const vars = await client.list({ project: 'my-project', environment: 'prd' })

await client.disconnect()

Dotenv Compatible

// Auto-load .env into process.env
import 'vaulter/load'

// Or with options
import { loader } from 'vaulter'
loader({ path: '.env.local', override: true })

MCP Server

Vaulter includes a Model Context Protocol (MCP) server for AI assistant integration.

Setup

# Start server
vaulter mcp

# Test with MCP Inspector
npx @anthropic-ai/mcp-inspector vaulter mcp

Claude Desktop Config

{
  "mcpServers": {
    "vaulter": {
      "command": "vaulter",
      "args": ["mcp"]
    }
  }
}

Available Tools (19)

Resources (7)

• vaulter://config — Project configuration
• vaulter://services — Monorepo services
• vaulter://keys — List all encryption keys (project + global)
• vaulter://keys/<name> — Specific key details
• vaulter://keys/global/<name> — Global key details
• vaulter://project/env — Environment variables
• vaulter://project/env/service — Service-specific vars
• vaulter://compare/env1/env2 — Environment diff

Prompts (5)

• setup_project — Initialize a new project
• migrate_dotenv — Migrate existing .env
• deploy_secrets — Deploy to Kubernetes
• compare_environments — Compare two environments
• security_audit — Audit for security issues

Pre-built Binaries

Download from Releases:

License

MIT © Forattini