Skip to main content

Getting Started

Welcome to EnvCat! This guide will help you get up and running with local-first secrets management in under 15 minutes.

What You'll Learn​

  • Installation: Set up EnvCat using Docker Compose
  • First Run: Create your first bundle and request secrets
  • Core Concepts: Understand bundles, device-approval flow, and encryption
  • Basic Usage: Use EnvCat in your daily workflow

Prerequisites​

Before you begin, make sure you have:

  • Docker & Docker Compose (v2.0+)
  • Operating System: Linux or macOS (Windows support coming soon)
  • Terminal: Basic command-line familiarity
  • Optional: Go 1.21+ (to build CLI from source)

System Requirements:

  • 2GB RAM minimum (4GB recommended)
  • 1GB free disk space
  • Ports 8888 and 8889 available (configurable)

Quick Navigation​

  1. Installation - Docker Compose setup and verification
  2. First Run - Create your first bundle and request secrets

Architecture at a Glance​

EnvCat consists of four services running via Docker Compose:

┌──────────────────────────────────────────────────┐
│  Your Machine (Docker Network: constants)       │
│                                                  │
│  ┌─────────┐  ┌────────┐  ┌──────┐  ┌────────┐ │
│  │  Redis  │  │  API   │  │ Web  │  │  Docs  │ │
│  │  :6379  │  │ :8080  │  │:8888 │  │ :8889  │ │
│  └────┬────┘  └───┬────┘  └───┬──┘  └────────┘ │
│       │           │            │                 │
│  Ephemeral    Bundles      Approval             │
│   Requests   (SQLite)         UI                │
└──────────────────────────────────────────────────┘
         ▲                       ▲
         │                       │
    CLI requests              Browser approves
    (Go binary)              (http://localhost:8888)

Ports:

  • 8888: Web UI (bundle management and approvals) - Public
  • 8889: Documentation site (this site!) - Public
  • 8080: API (Flask backend) - Internal only (not exposed to host)
  • 6379: Redis (ephemeral storage) - Internal only

Data Storage:

  • Redis: Ephemeral approval state (5-minute TTL)
  • SQLite: Bundle storage (api/data/app.db)
  • No cloud: Everything runs locally

Installation Paths​

Choose your installation method:

Best for: First-time users who want to try EnvCat quickly.

git clone https://github.com/check-the-vibe/envcat
cd EnvCat
docker compose up -d --build

→ Full installation guide

Option B: Development Setup​

Best for: Developers who want to modify or contribute to EnvCat.

git clone https://github.com/check-the-vibe/envcat
cd EnvCat

# Start services in dev mode
docker compose up --build

# In another terminal, build CLI
cd cli
go build -o envcat ./cmd/constants

→ See internal docs/DEVELOPMENT.md for development setup

What's Next?​

After installation, you'll:

  1. Verify installation - Check that all services are healthy
  2. Seed example bundle - Create sample data to test with
  3. Build CLI - Compile the Go binary
  4. Request your first secret - Experience the device-approval flow
  5. Use secrets in your shell - Inject variables or write .env files

→ Start here: Installation Guide

Core Concepts​

Before diving in, understand these key concepts:

Bundles​

Named sets of environment variables, like:

  • dev/myproject - Development environment for "myproject"
  • prod/api - Production API credentials
  • client-acme - Client-specific secrets for ACME Corp

Example:

Bundle: dev/myproject
├── API_KEY=sk_test_123...
├── DB_URL=postgres://localhost:5432/dev
└── STRIPE_KEY=sk_test_456...

Device-Approval Flow​

OAuth-style approval flow for requesting secrets:

  1. CLI initiates request → Generates ephemeral keypair, shows QR/URL
  2. User approves in browser → Selects bundle + keys to send
  3. Server encrypts to CLI → End-to-end encryption (sealed box)
  4. CLI decrypts locally → Outputs shell-safe exports

Why? No copy-paste, no long-lived tokens, ephemeral security.

Encryption Layers​

Two layers of encryption:

  1. At-rest encryption: Bundle values encrypted in SQLite (libsodium secretbox)

    • Encrypted with server-side key (BUNDLE_KMS_KEY)
    • Server can decrypt to re-encrypt for CLI

  2. End-to-end encryption: Secrets encrypted to CLI public key (sealed boxes)

    • Only the CLI can decrypt
    • Server never sees plaintext in this flow

→ Learn more: Security Model

Need Help?​

Community​

EnvCat is free and open-source (MIT license).

  • ⭐ Star us on GitHub: Support the project
  • 🐛 Report issues: Help us improve
  • 💡 Request features: Share your ideas
  • 🔧 Contribute: Pull requests welcome

Ready to start? → Installation Guide