Configuration

Initializing the Configuration File

Run the following command to create a default configuration file at ~/.clanker.yaml:

clanker config init

If the file already exists, the command will not overwrite it.

To view your current configuration:

clanker config show

Full Configuration Reference

Below is the complete configuration file with all supported sections and options. Copy this to ~/.clanker.yaml and customize it for your environment.

# Clanker Configuration
# Copy this to ~/.clanker.yaml and customize for your setup

# AI Providers Configuration
ai:
  default_provider: openai  # Default AI provider to use

  providers:
    bedrock:
      aws_profile: your-aws-profile  # AWS profile for Bedrock API calls
      model: anthropic.claude-opus-4-6-v1
      region: us-west-1

    openai:
      model: gpt-5
      api_key_env: OPENAI_API_KEY

    anthropic:
      model: claude-opus-4-6
      api_key_env: ANTHROPIC_API_KEY

    gemini:
      project_id: your-gcp-project-id

    gemini-api:
      model: gemini-2.5-flash
      api_key_env: GEMINI_API_KEY

    github-models:
      model: openai/gpt-5.4

    deepseek:
      model: deepseek-chat
      api_key_env: DEEPSEEK_API_KEY

    cohere:
      model: command-a-03-2025
      api_key_env: COHERE_API_KEY

    minimax:
      model: MiniMax-M2.5
      api_key_env: MINIMAX_API_KEY

# Infrastructure Providers Configuration
infra:
  default_environment: dev             # Default environment to use
  default_provider: aws                # Default infrastructure provider

  aws:
    environments:
      dev:
        profile: your-dev-profile
        region: us-east-1
        description: Development environment
      stage:
        profile: your-stage-profile
        region: us-east-1
        description: Staging environment
      prod:
        profile: your-prod-profile
        region: us-east-1
        description: Production environment

  gcp:
    project_id: your-gcp-project-id

github:
  token: ""                      # GitHub personal access token (optional for public repos)
  default_repo: your-repo        # Default repository to use
  repos:                         # List of GitHub repositories
    - owner: your-username
      repo: your-infrastructure-repo
      description: Infrastructure repository
    - owner: your-username
      repo: your-services-repo
      description: Services and database schemas
    - owner: your-username
      repo: your-app-repo
      description: Application repository

postgres:
  default_connection: dev  # Default PostgreSQL connection
  connections:             # PostgreSQL connections
    dev:
      host: localhost
      port: 5432
      database: your_dev_db
      username: postgres
      description: Development database
    stage:
      host: your-stage-db.example.com
      port: 5432
      database: your_stage_db
      username: app_user
      description: Staging database

terraform:
  default_workspace: dev  # Default Terraform workspace
  workspaces:             # Terraform workspaces
    dev:
      path: /path/to/your/infrastructure
      description: Development infrastructure
    stage:
      path: /path/to/your/infrastructure
      description: Staging infrastructure

codebase:
  paths:              # Paths to scan for code analysis
    - .
    - /path/to/your/services
    - /path/to/your/infrastructure
  exclude:            # Patterns to exclude
    - node_modules
    - .git
    - vendor
    - __pycache__
    - "*.log"
    - "*.tmp"
    - ".env*"
  max_file_size: 1048576  # Max file size to analyze (1MB)
  max_files: 100          # Max number of files to analyze per query

# Digital Ocean (for 'clanker do ...' and 'clanker ask --digitalocean ...'):
# digitalocean:
#   api_token: ""           # Or set DO_API_TOKEN / DIGITALOCEAN_ACCESS_TOKEN

# Hetzner Cloud (for 'clanker hetzner ...' and 'clanker ask --hetzner ...'):
# hetzner:
#   api_token: ""           # Or set HCLOUD_TOKEN

# Verda Cloud (for 'clanker verda ...' and 'clanker ask --verda ...'):
# verda:
#   client_id: ""            # Or set VERDA_CLIENT_ID
#   client_secret: ""        # Or set VERDA_CLIENT_SECRET
#   default_project_id: ""   # Or set VERDA_PROJECT_ID
#   default_location: ""     # e.g. "FIN-01", "ICE-01"
#   default_ssh_key_id: ""
#   ssh_key_path: "~/.ssh/id_ed25519"

# General settings
timeout: 30  # Timeout for AI requests in seconds

Configuration Sections Explained

AI Providers (ai)

The ai section controls which language model provider Clanker uses and how it authenticates.

• default_provider -- The provider used when no --ai-profile flag is specified. Common values: openai, anthropic, bedrock, gemini-api, deepseek, cohere, minimax, github-models.

• providers -- A map of named provider configurations. Each provider has its own authentication mechanism:

  • bedrock uses your AWS profile and region. No separate API key is needed.
  • openai, anthropic, deepseek, cohere, minimax, and gemini-api use API keys, either set directly or referenced via an environment variable name in api_key_env.
  • gemini (without the -api suffix) uses Google Application Default Credentials.
  • github-models uses the GitHub Models marketplace; authentication is handled through your GitHub session.

You can override the provider and model at runtime using flags like --ai-profile, --openai-model, --anthropic-model, and so on.

Infrastructure Environments (infra)

The infra section defines your cloud environments and their credentials.

• default_environment -- Which named environment to use by default (for example, dev, stage, or prod).
• default_provider -- Which cloud provider to assume when no explicit provider flag is given.
• aws.environments -- A map of named environments, each with an AWS CLI profile, region, and optional description. Clanker uses these profiles to authenticate with AWS.
• gcp.project_id -- The default GCP project ID for GCP operations.

GitHub (github)

Configure GitHub access for repository queries, pull request analysis, and workflow inspection.

• token -- A GitHub personal access token. Optional for public repositories; required for private repositories.
• default_repo -- The repository name used when no repo is specified.
• repos -- A list of repositories Clanker can query, each with an owner, repo, and description.

PostgreSQL (postgres)

Configure PostgreSQL connections for database queries.

• default_connection -- Which named connection to use by default.
• connections -- A map of named database connections, each with host, port, database, username, and description.

Terraform (terraform)

Configure Terraform workspaces for state and plan queries.

• default_workspace -- Which workspace to use by default.
• workspaces -- A map of named workspaces, each with a path to the Terraform working directory and a description.

Codebase (codebase)

Configure codebase scanning for code analysis queries.

• paths -- Directories to include when scanning for code.
• exclude -- Glob patterns to exclude from scanning.
• max_file_size -- Maximum file size in bytes to analyze (default: 1MB).
• max_files -- Maximum number of files to analyze per query (default: 100).

DigitalOcean (digitalocean)

• api_token -- Your DigitalOcean API token. Can also be set via the DO_API_TOKEN or DIGITALOCEAN_ACCESS_TOKEN environment variables.

Hetzner (hetzner)

• api_token -- Your Hetzner Cloud API token. Can also be set via the HCLOUD_TOKEN environment variable.

Verda (verda)

Verda Cloud (ex-DataCrunch) uses OAuth2 Client Credentials.

• client_id -- OAuth2 client ID. Env override: VERDA_CLIENT_ID.
• client_secret -- OAuth2 client secret. Env override: VERDA_CLIENT_SECRET.
• default_project_id -- Project UUID for scoping. Env override: VERDA_PROJECT_ID.
• default_location -- Default datacenter code (FIN-01, ICE-01, …) used by maker plans and k8s create verda-instant.
• default_ssh_key_id -- SSH key UUID attached to new instances/clusters by default.
• ssh_key_path -- Local private key used by the verda-instant k8s provider to pull /root/.kube/config off a cluster's head node. Defaults to ~/.ssh/id_ed25519.

Clanker reads credentials from (in order): ~/.clanker.yaml → VERDA_* env vars → ~/.verda/credentials (written by verda auth login) → the Clanker backend credential store (when a backend API key is configured).

The ~/.clanker/ Directory

Clanker stores runtime data in the ~/.clanker/ directory. This includes:

• Conversation history -- When using clanker k8s ask, conversation context is persisted per cluster so follow-up questions work across sessions.
• Resource tracking database -- The maker and deploy pipelines store metadata about created resources for tracking and cleanup.
• Agent state -- The Hermes agent and other sub-agents may store session state here.

This directory is created automatically and does not need manual configuration.

AWS Profile Integration

Clanker does not store AWS access keys in its configuration file. Instead, it uses your locally configured AWS CLI profiles. This approach provides several benefits:

• Credentials are managed through the standard AWS credential chain (environment variables, ~/.aws/credentials, IAM roles, SSO).
• You can use temporary session tokens and assume-role configurations.
• Multi-account setups are handled naturally through named profiles.

To set up an AWS profile:

aws configure --profile your-profile-name

Clanker resolves the AWS profile in the following order:

1. The --profile flag passed on the command line.
2. The profile configured for the default environment in infra.aws.environments.<env>.profile.
3. The aws.default_profile configuration value.
4. The literal string default.

Environment Variables

Clanker reads API keys from the following environment variables. These can also be configured in ~/.clanker.yaml under the respective provider's api_key_env field.

Variable	Provider	Description
OPENAI_API_KEY	OpenAI	API key for OpenAI models (GPT-5, etc.)
ANTHROPIC_API_KEY	Anthropic	API key for Anthropic models (Claude Opus, etc.)
GEMINI_API_KEY	Gemini API	API key for Google Gemini models
DEEPSEEK_API_KEY	DeepSeek	API key for DeepSeek models
COHERE_API_KEY	Cohere	API key for Cohere models (Command A, etc.)
MINIMAX_API_KEY	MiniMax	API key for MiniMax models
DO_API_TOKEN	DigitalOcean	DigitalOcean API token (alternative: DIGITALOCEAN_ACCESS_TOKEN)
HCLOUD_TOKEN	Hetzner	Hetzner Cloud API token
CLOUDFLARE_API_TOKEN	Cloudflare	Cloudflare API token
CLOUDFLARE_ACCOUNT_ID	Cloudflare	Cloudflare account ID
VERDA_CLIENT_ID	Verda	Verda OAuth2 client ID
VERDA_CLIENT_SECRET	Verda	Verda OAuth2 client secret
VERDA_PROJECT_ID	Verda	Verda project UUID (optional)

You can also pass API keys directly on the command line using flags like --openai-key, --anthropic-key, --gemini-key, and so on. Command-line flags take the highest priority, followed by configuration file values, then environment variables.

Scanning for Credentials

To see which credentials and CLI tools Clanker can detect on your system, run:

clanker config scan

This command checks for:

• AWS profiles in ~/.aws/credentials and ~/.aws/config
• GCP Application Default Credentials and gcloud configurations
• Azure CLI subscriptions
• Cloudflare API tokens in environment variables
• DigitalOcean API tokens
• Hetzner Cloud API tokens
• LLM API keys in environment variables

For JSON output suitable for automation:

clanker config scan --output json

You can also specify custom paths and environment variable names to scan:

clanker config scan --aws-paths ~/.custom/aws-creds --llm-env MY_OPENAI_KEY,MY_ANTHROPIC_KEY