Skip to content
CAPA CAPA CAPA Docs

Credentials

Keep API keys and tokens out of capabilities.yaml. Use capa placeholders for install-time secrets, and capa auth when remotes need git OAuth.

Placeholders

Section titled “Placeholders”

Anywhere in the capabilities file (for example server env or headers), write ${VarName}:

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

capa resolves ${VarName} at install time. These are not shell variables and are not expanded into provider hook environments as process env by default.

Provide values at install

Section titled “Provide values at install”

You can supply placeholder values in two ways:

MethodHow
Web UIRun capa install (managed). capa opens a local prompt for missing variables.
.env fileRun capa install -e (loads project .env) or capa install -e .prod.env
Terminal window
# .env — keys match the placeholder name without ${}
BraveApiKey=your-api-key


capa install -e
capa install -e .staging.env

Resolved values are stored per project in ~/.capa/capa.db. Subsequent installs reuse stored credentials unless you replace them via the UI or another -e file.

Private git (OAuth)

Section titled “Private git (OAuth)”

Skills, plugins, rules, and agent snippets from private GitHub or GitLab repos need git authentication. Authenticate once with:

Terminal window
capa auth                 # default Git provider
capa auth github.com
capa auth gitlab.com

capa stores those credentials securely in the capa database and uses them when cloning or updating remotes during install (and when warming the cache).

Checklist

Section titled “Checklist”
  1. Replace literal secrets in the capabilities file with ${VarName} placeholders.
  2. Run capa auth <host> if any remotes are private.
  3. Run capa install and complete the web UI prompts, or capa install -e with a local env file.
  4. Confirm tools that need those env vars work via your client or capa sh.
Section titled “Related”