Quickstart: Run Vault Locally

Setup Steps

Clone the stack repository

git clone https://github.com/brainz-lab/stack.git
cd stack

Create your environment file

cp .env.example .env

The defaults work for local development. No changes needed.

Generate secret keys

Run the setup script to generate all required keys:

./scripts/setup.sh

Start the services

This starts Vault along with its dependencies (PostgreSQL, Redis):

docker-compose up -d vault timescaledb redis traefik

Tip: To run the full stack (all services), use ./scripts/start.sh

Add hosts entry (optional but recommended)

For subdomain routing, add to /etc/hosts:

127.0.0.1 vault.localhost

✓

Access Vault

Open your browser:

http://vault.localhost ↗ or http://localhost:3006 ↗

Store Your First Secret

Once Vault is running, store and retrieve secrets from your Rails app.

1. Add the SDK to your Gemfile

gem 'brainzlab'

2. Configure the initializer

# config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  config.vault_url = "http://vault.localhost"
  config.vault_api_key = "your_api_key_from_env"
end

3. Store and retrieve secrets

# Store a secret
BrainzLab::Vault.set("stripe/api_key", "sk_live_xxx")
BrainzLab::Vault.set("aws/access_key", "AKIA...")

# Retrieve a secret
api_key = BrainzLab::Vault.get("stripe/api_key")

# Use in your app
Stripe.api_key = BrainzLab::Vault.get("stripe/api_key")

# Delete a secret
BrainzLab::Vault.delete("old/unused_key")

4. Use environment-specific secrets

# Secrets are scoped by environment
BrainzLab::Vault.set("stripe/api_key", "sk_test_xxx", environment: "development")
BrainzLab::Vault.set("stripe/api_key", "sk_live_xxx", environment: "production")

# Automatically uses current Rails environment
api_key = BrainzLab::Vault.get("stripe/api_key")

Find your API key: Check the VAULT_API_KEY in your .env file after running setup.

Claude MCP Integration

Let Claude access your secrets securely via MCP.

# Add to your Claude Desktop config
{
  "mcpServers": {
    "vault": {
      "command": "curl",
      "args": ["-N", "http://vault.localhost/mcp"]
    }
  }
}

Now Claude can securely retrieve secrets when you ask:

"Get the Stripe API key from Vault and use it to check our balance."

Useful Commands

View logs

docker-compose logs -f vault

Stream Vault's application logs in real-time.

Stop services

docker-compose down

Stop and remove all running containers.

Restart Vault

docker-compose restart vault

Restart just the Vault service.

Health check

curl http://localhost:3006/up

Verify Vault is healthy and responding.

Reset everything

./scripts/reset.sh

Stop services, remove volumes, start fresh. Warning: deletes all secrets!

Troubleshooting

Port 3006 already in use

Something else is using the port. Find and stop it:

lsof -i :3006
kill -9 <PID>

Database connection errors

Make sure TimescaleDB is healthy:

docker-compose ps timescaledb
docker-compose logs timescaledb

API key not working

Check the API key was generated correctly:

grep VAULT_API_KEY .env

Run Vault Locally

Prerequisites