Environment Variables

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"

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.

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"

Value	Behavior
`"true"`	Enable local MCP servers (default when not set)
Any other value	Disable local MCP servers

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"

CRAFT_DEEPLINK_SCHEME

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:

CRAFT_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY environment variable
CRAFT_CLAUDE_OAUTH_TOKEN environment variable (for OAuth)
Stored credential in ~/.craft-agent/credentials.enc
Interactive prompt (if running interactively)

For API base URL:

ANTHROPIC_BASE_URL environment variable
Connection base URL (configured in LLM connections)
Default (https://api.anthropic.com)

For model selection:

LLM connection default model (if set)
App-level model defaults (per provider)
System default (Claude Sonnet)

For configuration directory:

CRAFT_CONFIG_DIR environment variable
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

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