Credentials Management

CAPA provides secure credential management for API keys and sensitive values used by MCP servers and tools.

Variable Substitution

Use ${VariableName} syntax in your capabilities file for sensitive values:

servers:
  - id: brave
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-brave-search
      env:
        BRAVE_API_KEY: ${BraveApiKey}

  - id: github
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-github
      env:
        GITHUB_TOKEN: ${GitHubToken}
        GITHUB_ORG: ${GitHubOrg}

{
  "servers": [
    {
      "id": "brave",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-brave-search",
        "env": {
          "BRAVE_API_KEY": "${BraveApiKey}"
        }
      }
    },
    {
      "id": "github",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-github",
        "env": {
          "GITHUB_TOKEN": "${GitHubToken}",
          "GITHUB_ORG": "${GitHubOrg}"
        }
      }
    }
  ]
}

Credential Management Options

CAPA provides two ways to manage credentials:

Option 1: Web UI (Default)

When you run capa install, CAPA automatically opens a web UI at http://localhost:5912 to collect required credentials.

Features:

User-friendly interface
Credentials stored securely in local database
Encrypted storage at ~/.capa/capa.db
Values never appear in your capabilities file

Usage:

capa install
# Opens web UI automatically for credential input

Option 2: Environment File

Provide credentials via a .env file for automated workflows or CI/CD:

Create a .env file:

# .env
BraveApiKey=your-api-key-here
GitHubToken=ghp_token123
GitHubOrg=my-org
DatabaseUrl=postgresql://localhost:5432/db

Install with .env file:

# Use default .env file
capa install -e

# Use custom env file
capa install -e .prod.env
capa install --env .staging.env

Notes:

The env file must exist or the command will fail
All required variables must be present
Comments (lines starting with #) are supported
Empty lines are ignored

Environment File Format

# API Keys
BraveApiKey=your-brave-api-key
GitHubToken=ghp_yourtoken123

# Configuration
DatabaseUrl=postgresql://localhost:5432/mydb
ApiEndpoint=https://api.example.com

# Multiline values (quote them)
PrivateKey="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQ...
-----END PRIVATE KEY-----"

Security Best Practices

1. Never Commit Credentials

Add .env files to your .gitignore:

# .gitignore
.env
.env.*
!.env.example

2. Use .env.example for Documentation

Create a template for your team:

# .env.example
BraveApiKey=your-brave-api-key-here
GitHubToken=your-github-token-here
GitHubOrg=your-github-org

3. OAuth Token Resilience

As of v1.9.2, CAPA retains Git OAuth tokens on transient refresh failures (5xx errors, network issues, rate limits) instead of deleting them. Tokens are only removed on permanent failures like invalid_grant or explicit revocation. This prevents spurious re-authentication when a provider has a brief outage.

4. Rotate Credentials Regularly

To update credentials, either:

Run capa install again (web UI will prompt for new values)
Update your .env file and run capa install -e

4. Use Restricted API Keys

Create API keys with minimal required permissions for each service.

Credential Storage

When using the web UI, credentials are stored in:

~/.capa/capa.db

Storage characteristics:

SQLite database with encryption
Credentials are project-specific (identified by project ID)
Never exposed in logs or process lists
Persisted across server restarts

Managing Stored Credentials

View and Edit Stored Credentials

The project credentials page in the web UI (opened during capa install or at http://localhost:5912) shows both the list of required variables and their current stored values. You can view and update credentials there; the API returns variable values so the UI can display and edit them. CAPA does not expose a CLI command to print stored values for security reasons.

Clear Credentials

To remove stored credentials for a project:

# Stop the server
capa stop

# Remove the database (removes ALL credentials)
rm ~/.capa/capa.db

# Reinstall and provide new credentials
capa install

CI/CD Integration

For automated deployments, use environment files with CI/CD secrets:

GitHub Actions Example

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Create .env file
        run: |
          echo "BraveApiKey=${{ secrets.BRAVE_API_KEY }}" >> .env
          echo "GitHubToken=${{ secrets.GITHUB_TOKEN }}" >> .env
      
      - name: Install CAPA
        run: |
          curl -LsSf https://capa.infragate.ai/install.sh | sh
          capa install -e

Troubleshooting

Web UI Not Opening

Check if port 5912 is available
Manually navigate to http://localhost:5912
Check firewall settings

Variable Not Substituted

Ensure exact ${VariableName} format (case-sensitive)
Verify the variable name matches in both capabilities file and .env file
Check for typos in variable names

.env File Not Found

Verify the file path is correct
Use absolute path if needed: capa install -e /full/path/to/.env
Check file permissions