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.

​
AWS Credentials (Bedrock)

When using AWS Bedrock with authType: "environment", the subprocess inherits standard AWS environment variables from your shell: 
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."     # optional, for STS temporary credentials
export AWS_REGION="us-east-1"      # or set awsRegion in the connection config
export AWS_PROFILE="my-profile"    # use a named profile from ~/.aws/credentials
These follow the standard AWS SDK credential chain — ~/.aws/credentials, SSO sessions, IAM roles, and instance profiles all work.
With authType: "iam_credentials", credentials are entered in the UI and injected into the subprocess automatically. You do not need to set these env vars in that case.

​
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"

​
Server Mode Variables

These configure the remote server when running in standalone or embedded mode.

​
CRAFT_SERVER_TOKEN

Bearer token for server authentication. Required for both server and client. 
export CRAFT_SERVER_TOKEN=$(openssl rand -hex 32)

​
CRAFT_SERVER_URL

Server URL for client connections. Set this on the client side to connect to a remote server. 
export CRAFT_SERVER_URL=wss://your-server:9100

​
CRAFT_RPC_HOST

Bind address for the server. Defaults to 127.0.0.1 (localhost only). Set to 0.0.0.0 to accept remote connections. 
export CRAFT_RPC_HOST=0.0.0.0

​
CRAFT_RPC_PORT

Server port. Defaults to 9100. 
export CRAFT_RPC_PORT=9100

​
CRAFT_RPC_TLS_CERT / CRAFT_RPC_TLS_KEY

PEM certificate and private key files for TLS. Required for remote connections (wss://). Can be omitted for localhost development. 
export CRAFT_RPC_TLS_CERT=/path/to/cert.pem
export CRAFT_RPC_TLS_KEY=/path/to/key.pem

​
CRAFT_RPC_TLS_CA

Optional PEM CA chain file for custom certificate authorities. 
export CRAFT_RPC_TLS_CA=/path/to/ca.pem

​
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 "..."