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

        clanker-cloud:
            model: gemini-3.5-flash
            base_url: https://clanker-auth-gw-zc0ce3o.uk.gateway.dev/v1/llm
            api_key_env: CLANKER_CLOUD_AUTH_TOKEN

        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

    azure:
        subscription_id: your-azure-subscription-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

sentry:
    auth_token: "" # Or set SENTRY_AUTH_TOKEN
    org_slug: "" # Or set SENTRY_ORG
    default_project: "" # Or set SENTRY_PROJECT
    host: "sentry.io"

linear:
    api_key: "" # Or set LINEAR_API_KEY
    workspace_id: "" # Or set LINEAR_WORKSPACE_ID
    default_team: "" # Or set LINEAR_TEAM

notion:
    integration_token: "" # Or set NOTION_API_KEY
    default_database_id: "" # Or set NOTION_DATABASE_ID

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

# DigitalOcean (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

# Vercel (for 'clanker vercel ...' and 'clanker ask --vercel ...'):
# vercel:
#   api_token: ""           # Or set VERCEL_TOKEN / VERCEL_API_TOKEN
#   team_id: ""             # Or set VERCEL_TEAM_ID / VERCEL_ORG_ID

# Fly.io (for 'clanker fly ...' and 'clanker ask --flyio ...'):
# flyio:
#   api_token: ""           # Or set FLY_API_TOKEN / FLY_ACCESS_TOKEN
#   org_slug: ""            # Or set FLY_ORG / FLY_ORG_SLUG

# Railway (for 'clanker railway ...' and 'clanker ask --railway ...'):
# railway:
#   api_token: ""           # Or set RAILWAY_API_TOKEN
#   workspace_id: ""        # Or set RAILWAY_WORKSPACE_ID

# Tencent Cloud (for 'clanker tencent ...' and 'clanker ask --tencent ...'):
# tencent:
#   secret_id: ""           # Or set TENCENTCLOUD_SECRET_ID / TENCENT_SECRET_ID
#   secret_key: ""          # Or set TENCENTCLOUD_SECRET_KEY / TENCENT_SECRET_KEY
#   region: ap-singapore    # Or set TENCENTCLOUD_REGION / TENCENT_REGION

# 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, clanker-cloud, 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.
  • clanker-cloud sends requests through the Clanker Cloud LLM endpoint using CLANKER_CLOUD_AUTH_TOKEN.

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.
• azure.subscription_id -- The default Azure subscription ID for Azure 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.

Sentry (sentry)

• auth_token -- Sentry User Auth Token. Env override: SENTRY_AUTH_TOKEN.
• org_slug -- Sentry organization slug. Env override: SENTRY_ORG.
• default_project -- Optional project slug. Env override: SENTRY_PROJECT.
• host -- Sentry host. Env override: SENTRY_HOST.

Linear (linear)

• api_key -- Linear Personal API Key. Env override: LINEAR_API_KEY.
• workspace_id -- Optional workspace UUID. Env override: LINEAR_WORKSPACE_ID.
• default_team -- Optional team key. Env override: LINEAR_TEAM.

Notion (notion)

• integration_token -- Notion internal integration token. Env override: NOTION_API_KEY.
• default_database_id -- Optional default database ID. Env override: NOTION_DATABASE_ID.

Notion integrations only see pages and databases explicitly shared with the integration in Notion.

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.

Vercel (vercel)

• api_token -- Vercel API token. Can also be set via VERCEL_TOKEN or VERCEL_API_TOKEN.
• team_id -- Optional team ID. Can also be set via VERCEL_TEAM_ID or VERCEL_ORG_ID.

Fly.io (flyio)

• api_token -- Fly.io API token. Can also be set via FLY_API_TOKEN or FLY_ACCESS_TOKEN.
• org_slug -- Optional organization filter. Can also be set via FLY_ORG or FLY_ORG_SLUG.

Railway (railway)

• api_token -- Railway account API token. Can also be set via RAILWAY_API_TOKEN.
• workspace_id -- Optional Railway workspace/team ID. Can also be set via RAILWAY_WORKSPACE_ID.

Tencent Cloud (tencent)

• secret_id -- Tencent Cloud CAM secret ID. Can also be set via TENCENTCLOUD_SECRET_ID or TENCENT_SECRET_ID.
• secret_key -- Tencent Cloud CAM secret key. Can also be set via TENCENTCLOUD_SECRET_KEY or TENCENT_SECRET_KEY.
• region -- Default Tencent Cloud region. Can also be set via TENCENTCLOUD_REGION or TENCENT_REGION. Defaults to ap-singapore.

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
CLANKER_CLOUD_AUTH_TOKEN	Clanker Cloud	Auth token for the hosted Clanker Cloud LLM endpoint
DO_API_TOKEN	DigitalOcean	DigitalOcean API token (alternative: DIGITALOCEAN_ACCESS_TOKEN)
HCLOUD_TOKEN	Hetzner	Hetzner Cloud API token
VERCEL_TOKEN	Vercel	Vercel API token (alternative: VERCEL_API_TOKEN)
FLY_API_TOKEN	Fly.io	Fly.io API token (alternative: FLY_ACCESS_TOKEN)
RAILWAY_API_TOKEN	Railway	Railway account API token
SENTRY_AUTH_TOKEN	Sentry	Sentry User Auth Token
LINEAR_API_KEY	Linear	Linear Personal API Key
NOTION_API_KEY	Notion	Notion integration token
TENCENTCLOUD_SECRET_ID	Tencent Cloud	Tencent Cloud CAM secret ID
TENCENTCLOUD_SECRET_KEY	Tencent Cloud	Tencent Cloud CAM secret key
TENCENTCLOUD_REGION	Tencent Cloud	Default Tencent Cloud region
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
• Vercel, Fly.io, Railway, Sentry, Linear, and Notion environment variables
• Tencent Cloud secret ID / secret key
• 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

For provider dependency readiness and install commands, use:

clanker onboarding scan --format json
clanker onboarding install --dry-run --provider aws,gcp,azure,kubernetes