Skip to main content

​
API Configuration

These environment variables are required for authenticating with AI providers.
​
ANTHROPIC_API_KEY
string
API key for Anthropic Claude models.
export ANTHROPIC_API_KEY="sk-ant-api03-..."
You can also use the OAuth configuration flow:
agentuse auth login anthropic
​
OPENAI_API_KEY
string
API key for OpenAI GPT models.
export OPENAI_API_KEY="sk-proj-..."
​
OPENROUTER_API_KEY
string
API key for OpenRouter service.
export OPENROUTER_API_KEY="sk-or-v1-..."

​
Custom API Key Suffixes

You can use multiple API keys by adding suffixes: 
# For development environment
export ANTHROPIC_API_KEY_DEV="sk-ant-api03-dev..."
export OPENAI_API_KEY_DEV="sk-proj-dev..."

# For production environment  
export ANTHROPIC_API_KEY_PROD="sk-ant-api03-prod..."
export OPENAI_API_KEY_PROD="sk-proj-prod..."
Then reference them in your agent: 
---
model: anthropic:claude-sonnet-4-0:dev  # Uses ANTHROPIC_API_KEY_DEV
---

​
Behavior Control

​
MAX_STEPS
number
Override the maximum number of conversation steps an agent can take. Default: 1000
export MAX_STEPS="2000"
This prevents infinite loops and controls agent execution time.

​
Context Management

​
CONTEXT_COMPACTION
boolean
Enable or disable automatic context compaction when approaching model limits. Default: true (enabled)
# Disable context compaction
export CONTEXT_COMPACTION="false"
When enabled, AgentUse automatically compacts older messages when context approaches the model’s token limit.
​
COMPACTION_THRESHOLD
number
Percentage of context limit to trigger compaction. Default: 0.7 (70%)
export COMPACTION_THRESHOLD="0.8"  # Trigger at 80%
Must be a decimal between 0 and 1.
​
COMPACTION_KEEP_RECENT
number
Number of recent messages to preserve during compaction. Default: 3
export COMPACTION_KEEP_RECENT="5"  # Keep last 5 messages
These messages are never compacted to maintain conversation flow.

​
Logging and Debug

​
LOG_LEVEL
string
Set the logging level for AgentUse output. Default: INFO
export LOG_LEVEL="DEBUG"  # Available: DEBUG, INFO, WARN, ERROR
Controls which messages are displayed during execution.
​
DEBUG
boolean
Enable debug logging and verbose output. Default: false
export DEBUG="true"   # or DEBUG="1"
Shows detailed execution information, tool calls, and internal state.

​
Development Variables

​
NODE_TLS_REJECT_UNAUTHORIZED
string
For local development with self-signed certificates (HTTPS testing).
# Only for development - allows self-signed certs
export NODE_TLS_REJECT_UNAUTHORIZED="0"
Never use this in production. It disables SSL certificate verification.

​
MCP Server Environment Variables

Security by Design: AgentUse intentionally prevents hardcoding secrets in .agentuse files. All sensitive values must come from environment variables, keeping your secrets secure and out of version control.

​
The Security Model

MCP servers can access environment variables through two fields:
  • requiredEnvVars: Variables that MUST exist or the agent fails immediately
  • allowedEnvVars: Variables that are passed through if they exist (optional)
---
model: anthropic:claude-sonnet-4-0
mcp_servers:
  notion:
    command: "pnpx"
    args: ["-y", "@notionhq/notion-mcp-server"]
    requiredEnvVars:
      - NOTION_API_KEY        # Fails immediately if missing
    allowedEnvVars:
      - NOTION_DEBUG_MODE     # Optional, warns if missing
      - NOTION_WORKSPACE_ID   # Optional, warns if missing
---

​
Why This Design?

  1. No Secrets in Code: .agentuse files are often committed to version control
  2. Clear Requirements: Developers know exactly what env vars are needed
  3. Early Failure: Missing required vars fail fast with clear error messages
  4. Security Allowlist: Only explicitly allowed vars are passed to MCP servers

​
Setting Environment Variables

​
Error Messages

AgentUse provides clear, actionable error messages: 
# Missing required variable
Error: Missing required environment variables for MCP server 'notion': NOTION_API_KEY
Please set these in your .env file or export them in your shell.

# Missing optional variable (warning only)
[WARN] Optional environment variable 'NOTION_DEBUG_MODE' not set for server 'notion'

# Connection failure with hint
Failed to connect to MCP server 'github'
Note: The following optional environment variables are not set: GITHUB_TOKEN
If this server requires these variables, please set them in your .env file.

​
Complete Example

---
model: anthropic:claude-sonnet-4-0
mcp_servers:
  # API-based service requiring authentication
  notion:
    command: "pnpx"
    args: ["-y", "@notionhq/notion-mcp-server"]
    requiredEnvVars:
      - NOTION_API_KEY    # Must be set or fails
    allowedEnvVars:
      - NOTION_DEBUG      # Optional debug flag
      
  # Database connection
  postgres:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-postgresql"]
    requiredEnvVars:
      - DATABASE_URL      # Required connection string
    allowedEnvVars:
      - PG_STATEMENT_TIMEOUT  # Optional timeout
      - PG_POOL_SIZE          # Optional pool config
      
  # Local filesystem (no auth needed)
  filesystem:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    # No env vars needed for local filesystem
---
With .env file: 
# Required vars (agent won't start without these)
NOTION_API_KEY=secret_abc123
DATABASE_URL=postgresql://user:pass@localhost/mydb

# Optional vars (agent works without these)
NOTION_DEBUG=true
PG_POOL_SIZE=20

​
Using .env Files

AgentUse automatically loads .env files if present in your project directory: 
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
OPENROUTER_API_KEY=sk-or-v1-...
GITHUB_TOKEN=ghp_...
DATABASE_URL=postgresql://user:pass@localhost/db

# Behavior control
MAX_STEPS=500

# Context management
CONTEXT_COMPACTION=true
COMPACTION_THRESHOLD=0.7
COMPACTION_KEEP_RECENT=3

# Logging and debug
LOG_LEVEL=INFO
DEBUG=false
Never commit .env files to version control. Add them to .gitignore.

​
Priority Order

Environment variables are loaded in this order (later overrides earlier):
  1. System environment variables
  2. .env file in current directory
  3. Command-line environment variables
Example: 
# This overrides any existing MAX_STEPS value
MAX_STEPS=100 agentuse run agent.agentuse

​
Security Best Practices

​
Store Secrets Securely

Never hardcode API keys in agent files: 
# ❌ Bad - Would be insecure (but AgentUse doesn't allow this)
mcp_servers:
  github:
    env:
      GITHUB_TOKEN: "ghp_actualTokenHere"  # Not supported by design!

# ✅ Good - Use environment variable allowlist
mcp_servers:
  github:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    requiredEnvVars:
      - GITHUB_TOKEN  # Must be in .env or shell environment

​
Use .gitignore

Always exclude sensitive files: 
# Environment files
.env
.env.local
.env.*.local

# API keys
*.key
*.pem

​
Validate Required Variables

For MCP servers that require specific environment variables, they will fail with clear error messages if the variables are not set.

​
Troubleshooting

Verify the environment variable is set:
echo $ANTHROPIC_API_KEY
If empty, set it:
export ANTHROPIC_API_KEY="your-key-here"
Or use the auth command:
agentuse auth login
Check which key is being used:
agentuse auth list
The tool prioritizes OAuth tokens over API keys for Anthropic.
Ensure you’re setting it before running the agent:
export MAX_STEPS=100
agentuse run agent.agentuse

# Or inline:
MAX_STEPS=100 agentuse run agent.agentuse

​
Next Steps

Model Configuration

Set up model providers and API keys

MCP Configuration

Configure MCP servers
⌘I