Skip to main content
Environment variables provide configuration and credentials for automation and server deployment scenarios.

​
Supported Variables

​
ANTHROPIC_API_KEY / CRAFT_ANTHROPIC_API_KEY

Provide an Anthropic API key without storing it locally. Both names are supported; CRAFT_ANTHROPIC_API_KEY takes precedence if both are set. 
export ANTHROPIC_API_KEY="sk-ant-api03-..."
craft -p "Check my tasks"

​
CRAFT_CLAUDE_OAUTH_TOKEN

Provide a Claude OAuth token (for Claude Pro/Max subscriptions) without storing it locally. 
export CRAFT_CLAUDE_OAUTH_TOKEN="your-oauth-token"

​
ANTHROPIC_BASE_URL

Override the API endpoint URL. This is set automatically by Craft Agents when you configure a non-Anthropic provider (OpenRouter, Vercel AI Gateway, Ollama, or custom endpoint) via the UI. 
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
You can also set this manually to route all API calls through a custom endpoint: 
# Use OpenRouter
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

# Use local Ollama
export ANTHROPIC_BASE_URL="http://localhost:11434"
This variable is typically managed by Craft Agents based on your API Provider configuration. You only need to set it manually for automation or CI scenarios.

​
CRAFT_CONFIG_DIR

Override the default configuration directory. By default, Craft Agents stores configuration in ~/.craft-agent/. 
export CRAFT_CONFIG_DIR="/custom/path/to/config"
This affects the location of:
  • config.json
  • preferences.json
  • credentials.enc
  • Workspace configurations

​
CRAFT_LOCAL_MCP_ENABLED

Enable or disable local MCP server support (stdio subprocess servers). 
export CRAFT_LOCAL_MCP_ENABLED="false"
ValueBehavior
"true"Enable local MCP servers (default when not set)
Any other valueDisable local MCP servers
This variable requires the exact lowercase string "true" to enable. Values like "True", "TRUE", "yes", or "1" will be treated as disabled.
This can also be configured per-workspace in the workspace settings.

​
CRAFT_DEBUG

Enable debug logging for troubleshooting. When set, additional diagnostic information is written to the log file. 
export CRAFT_DEBUG="true"

​
Development Variables

These variables are primarily used for development and multi-instance scenarios.

​
CRAFT_VITE_PORT

Override the Vite dev server port. Automatically set when running from numbered instance folders. 
export CRAFT_VITE_PORT="5173"

​
CRAFT_APP_NAME

Override the application display name. Useful for distinguishing multiple instances. 
export CRAFT_APP_NAME="Craft Agents [Dev]"

​
CRAFT_INSTANCE_NUMBER

Instance identifier for multi-instance support. When set, adds a badge to the dock icon. 
export CRAFT_INSTANCE_NUMBER="1"
Custom deep link URL scheme. Default is craftagents. 
export CRAFT_DEEPLINK_SCHEME="craftagents1"

​
VITE_DEV_SERVER_URL

URL of the Vite development server. Used internally during development. 
export VITE_DEV_SERVER_URL="http://localhost:5173"

​
Precedence

For API credentials, the lookup order is:
  1. CRAFT_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY environment variable
  2. CRAFT_CLAUDE_OAUTH_TOKEN environment variable (for OAuth)
  3. Stored credential in ~/.craft-agent/credentials.enc
  4. Interactive prompt (if running interactively)
For API base URL:
  1. ANTHROPIC_BASE_URL environment variable
  2. Connection base URL (configured in LLM connections)
  3. Default (https://api.anthropic.com)
For model selection:
  1. LLM connection default model (if set)
  2. App-level model defaults (per provider)
  3. System default (Claude Sonnet)
For configuration directory:
  1. CRAFT_CONFIG_DIR environment variable
  2. Default ~/.craft-agent/

​
Usage Examples

​
CI/CD Pipeline

#!/bin/bash
export ANTHROPIC_API_KEY="${SECRETS_ANTHROPIC_KEY}"

craft -w "Work" -p "Generate release notes from recent commits"

​
Docker Container

ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ENV CRAFT_CONFIG_DIR=/app/config

CMD ["craft", "-w", "default", "-p", "..."]

​
Temporary Override

Use a different API key for one command: 
ANTHROPIC_API_KEY="sk-ant-different-key" craft -p "Quick check"

​
Custom Configuration Directory

export CRAFT_CONFIG_DIR="/home/user/.config/craft-agent"
craft -p "Using custom config location"

​
Security Notes

Avoid putting API keys directly in shell history or scripts. Use secret managers or secure environment injection.
Secure alternatives: 
# Read from file
export ANTHROPIC_API_KEY=$(cat ~/.secrets/anthropic-key)

# Read from secret manager
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value --secret-id anthropic-key --query SecretString --output text)

# Use .env file (not committed to git)
source .env && craft -p "..."