Environment Variables

Looplia uses environment variables for API keys, model configuration, and development settings.

API Keys

Variable	Description	Required
ANTHROPIC_API_KEY	Anthropic API key for Claude	Yes*
ZENMUX_API_KEY	ZenMux proxy API key	Yes*
OPENROUTER_API_KEY	OpenRouter API key	Yes*
OLLAMA_API_KEY	Ollama API key (defaults to “ollama”)	No
CLAUDE_CODE_OAUTH_TOKEN	Claude Code OAuth token (alternative auth)	No

Note

*Either ANTHROPIC_API_KEY, ZENMUX_API_KEY, or OPENROUTER_API_KEY is required, depending on your provider configuration. Alternatively, use CLAUDE_CODE_OAUTH_TOKEN with subscription presets. For Ollama, OLLAMA_API_KEY defaults to “ollama” if not set.

Setting API Keys

# Option 1: Export in current session
export ANTHROPIC_API_KEY=sk-ant-api03-...

# Option 2: Add to shell profile (~/.zshrc or ~/.bashrc)
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

# Option 3: Use .env file (for development)
echo 'ANTHROPIC_API_KEY=sk-ant-api03-...' >> .env
env $(cat .env) looplia run writing-kit --file test.md

OpenRouter Configuration

Use OpenRouter to access multiple AI providers through a single API with centralized model management:

# 1. Create preset in OpenRouter dashboard
# Visit: https://openrouter.ai/settings/presets
# - Click "Create Preset"
# - Name it exactly "looplia-default"
# - Select your preferred model (Claude, GPT-4, Gemini, etc.)
# - Configure routing, fallbacks, and providers
# - Save the preset

# 2. Set OpenRouter API key
export OPENROUTER_API_KEY=sk-or-v1-...

# 3. Apply preset
looplia config provider preset OPENROUTER_PRESET

# 4. Run workflow
looplia run writing-kit --file article.md

Benefits:

• Access 100+ models through one integration
• Change models via dashboard without reconfiguring looplia
• Use advanced routing (fallbacks, load balancing, cost optimization)
• Centralized billing and usage tracking

Tip

The preset name must be exactly looplia-default. You can update model selections in the OpenRouter dashboard at any time without changing looplia configuration.

Claude Code Subscription Authentication

Use your existing Claude Code subscription instead of separate API credits:

# 1. Apply a subscription preset
looplia config provider preset CLAUDE_CODE_SUBSCRIPTION_SONNET

# 2. Set CLAUDE_CODE_OAUTH_TOKEN environment variable
# On macOS, extract from Keychain:
export CLAUDE_CODE_OAUTH_TOKEN=$(security find-generic-password -s "Claude Code-credentials" -w | jq -r '.claudeAiOauth.accessToken')

# Or set directly if you have the token:
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

# 3. Run workflow
looplia run writing-kit --file article.md

Available subscription presets:

• CLAUDE_CODE_SUBSCRIPTION_HAIKU — Uses Claude Haiku 4.5
• CLAUDE_CODE_SUBSCRIPTION_SONNET — Uses Claude Sonnet 4.5
• CLAUDE_CODE_SUBSCRIPTION_OPUS — Uses Claude Opus 4.5

Tip

Add the token extraction to your ~/.zshrc or ~/.bashrc to automatically set the token on shell startup.

Model Configuration

Variable	Description	Default
LOOPLIA_AGENT_MODEL_MAIN	Override main agent model	Provider default
LOOPLIA_AGENT_MODEL_EXECUTOR	Override skill executor model	Provider default
ANTHROPIC_DEFAULT_HAIKU_MODEL	Override haiku tier model (SDK)	Main model
ANTHROPIC_DEFAULT_SONNET_MODEL	Override sonnet tier model (SDK)	Main model
ANTHROPIC_DEFAULT_OPUS_MODEL	Override opus tier model (SDK)	Main model

Note

Model tier variables (ANTHROPIC_DEFAULT_*_MODEL) are used by the Claude Agent SDK to map speed tiers (haiku, sonnet, opus) to actual model names. By default, all tiers use the main agent model from the preset configuration.

Model Override Examples

# Use Opus for main agent
export LOOPLIA_AGENT_MODEL_MAIN=claude-opus-4-20250514

# Use Haiku for executor (faster, cheaper)
export LOOPLIA_AGENT_MODEL_EXECUTOR=claude-haiku-4-20250514

# Run workflow
looplia run writing-kit --file article.md

Development Mode

Variable	Description	Default
LOOPLIA_DEV	Enable development mode	false
LOOPLIA_DEV_ROOT	Path to looplia-core source repository	-
LOOPLIA_HOME	Override workspace path	~/.looplia
LOOPLIA_DEBUG	Enable debug logging	false
LOOPLIA_OUTPUT_DIR	Default output directory for run command	cwd

Development Mode

When developing Looplia from source, use dev mode to load plugins directly without running init:

# Enable dev mode
export LOOPLIA_DEV=true
export LOOPLIA_DEV_ROOT=~/projects/looplia-core

# Run from any directory - plugins loaded from source
cd ~/my-content
looplia run writing-kit --file article.md

In dev mode:

• Plugins are loaded from $LOOPLIA_DEV_ROOT/plugins/
• Changes to plugin files take effect immediately
• No need to run looplia init after changes

Debug Logging

# Enable debug output
export LOOPLIA_DEBUG=1

# Run with verbose logging
looplia run writing-kit --file test.md

Debug logs are written to ~/.looplia/logs/.

Output Directory

Use LOOPLIA_OUTPUT_DIR to set a default output location for workflow results:

# Set default output directory
export LOOPLIA_OUTPUT_DIR=~/looplia-outputs

# Outputs will be copied here after each run
looplia run writing-kit --file article.md
# → Results in ~/looplia-outputs/

Priority order for output directory:

1. --output / -o flag (highest priority)
2. LOOPLIA_OUTPUT_DIR environment variable
3. Current working directory (default)

Custom Workspace Path

Use LOOPLIA_HOME to override the default workspace location:

# Use custom path
export LOOPLIA_HOME=/custom/path
looplia init

# Useful for testing
export LOOPLIA_HOME=$(mktemp -d)
looplia init --yes

This is useful for:

• Testing isolated installations
• Running multiple workspaces
• CI/CD with temporary directories

Provider Configuration

These variables work with the provider system:

Variable	Description
ANTHROPIC_API_KEY	Used when provider is anthropic
ZENMUX_API_KEY	Used when provider is zenmux (auto-mapped to ANTHROPIC_API_KEY for SDK)
OPENROUTER_API_KEY	Used when provider is openrouter (auto-mapped to ANTHROPIC_AUTH_TOKEN for SDK)
OLLAMA_API_KEY	Used when provider is ollama (auto-mapped to ANTHROPIC_API_KEY for SDK, defaults to “ollama”)

Auto-Mapping

Looplia automatically maps provider-specific API keys to ANTHROPIC_API_KEY for SDK compatibility (except OpenRouter, which uses ANTHROPIC_AUTH_TOKEN):

ZenMux:

# Set ZenMux key
export ZENMUX_API_KEY=sk-zenmux-...

# Configure ZenMux provider
looplia config provider preset ZENMUX_MINIMAX_M21

# The ZENMUX_API_KEY is automatically used
looplia run writing-kit --file article.md

OpenRouter:

# Set OpenRouter key
export OPENROUTER_API_KEY=sk-or-v1-...

# Configure OpenRouter provider
looplia config provider preset OPENROUTER_PRESET

# The OPENROUTER_API_KEY is automatically used
looplia run writing-kit --file article.md

Ollama:

# Optional: Set Ollama key (defaults to "ollama" if not set)
export OLLAMA_API_KEY=ollama

# Configure Ollama provider
looplia config provider preset OLLAMA_GLM47_CLOUD

# Uses OLLAMA_API_KEY or defaults to "ollama"
looplia run writing-kit --file article.md

Priority Order (v0.6.9+)

API Keys: Config file takes precedence when explicitly set:

1. Subscription auth (highest priority) — CLAUDE_CODE_OAUTH_TOKEN with subscription preset
2. Config file authToken — set via looplia config provider set auth-token
3. Endpoint-specific env var — ZENMUX_API_KEY for ZenMux, OPENROUTER_API_KEY for OpenRouter, OLLAMA_API_KEY for Ollama, ANTHROPIC_API_KEY for Anthropic
4. Default env var (ANTHROPIC_API_KEY)
5. Ollama default (lowest priority) — literal "ollama" string when provider is Ollama and no other auth is set

Model Settings: Environment variables take precedence:

1. Environment variables (highest priority)
2. Config file (~/.looplia/looplia.setting.json)
3. Default values (lowest priority)

# Model env vars still override config
export LOOPLIA_AGENT_MODEL_MAIN=claude-opus-4-20250514
looplia run writing-kit --file article.md

CI/CD Integration

For CI/CD pipelines, set variables in your pipeline configuration:

GitHub Actions

jobs:
  process:
    runs-on: ubuntu-latest
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bunx looplia init --yes
      - run: bunx looplia run writing-kit --file content.md --no-streaming

With Claude Code subscription:

jobs:
  process:
    runs-on: ubuntu-latest
    env:
      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bunx looplia init --yes
      - run: bunx looplia config provider preset CLAUDE_CODE_SUBSCRIPTION_SONNET
      - run: bunx looplia run writing-kit --file content.md --no-streaming

Docker

FROM oven/bun:latest
ENV ANTHROPIC_API_KEY=""
RUN bunx looplia init --yes
CMD ["bunx", "looplia", "run", "writing-kit", "--file", "/data/content.md"]

docker run -e ANTHROPIC_API_KEY=sk-ant-... -v ./content:/data my-looplia

All Variables Reference

Variable	Type	Description
ANTHROPIC_API_KEY	string	Anthropic API key
ZENMUX_API_KEY	string	ZenMux proxy API key
OPENROUTER_API_KEY	string	OpenRouter API key
OLLAMA_API_KEY	string	Ollama API key (defaults to “ollama”)
CLAUDE_CODE_OAUTH_TOKEN	string	OAuth token authentication
LOOPLIA_AGENT_MODEL_MAIN	string	Main agent model override
LOOPLIA_AGENT_MODEL_EXECUTOR	string	Executor model override
ANTHROPIC_DEFAULT_HAIKU_MODEL	string	Haiku tier model (SDK)
ANTHROPIC_DEFAULT_SONNET_MODEL	string	Sonnet tier model (SDK)
ANTHROPIC_DEFAULT_OPUS_MODEL	string	Opus tier model (SDK)
LOOPLIA_DEV	boolean	Enable development mode
LOOPLIA_DEV_ROOT	path	Development source path
LOOPLIA_HOME	path	Override workspace path (~/.looplia)
LOOPLIA_DEBUG	boolean	Enable debug logging
LOOPLIA_OUTPUT_DIR	path	Default output directory for run command

See Also

• Installation — Initial setup
• config Command — Configure via CLI
• Troubleshooting — Common issues