AgentUse - Autonomous Agents That Work Without You

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

ANTHROPIC_REFRESH_TOKEN

string

OAuth refresh token for Anthropic. Alternative to ANTHROPIC_API_KEY.Useful for Docker/container deployments where you want to use OAuth instead of API keys.

export ANTHROPIC_REFRESH_TOKEN="your-refresh-token"

To get your refresh token:

Run agentuse auth login anthropic locally
Extract from ~/.local/share/agentuse/auth.json

The token is automatically refreshed when expired and stored in memory.

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-5:dev  # Uses ANTHROPIC_API_KEY_DEV
---

Serve Mode

AGENTUSE_API_KEY

string

API key for authenticating requests to the serve mode HTTP server. Required when binding to exposed hosts (not 127.0.0.1 or localhost).

export AGENTUSE_API_KEY="your-secret-key"
agentuse serve --host 0.0.0.0

Clients authenticate via Bearer token:

curl -X POST http://server:12233/run \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"agent": "my-agent.agentuse"}'

Behavior Control

MAX_STEPS

number

Override the maximum number of conversation steps (LLM generation cycles) an agent can take. Default: 100

export MAX_STEPS="200"

Precedence: This environment variable overrides the maxSteps value in agent YAML files.This prevents infinite loops and controls cost by limiting the number of LLM calls. Each step typically involves an LLM generation with potential tool calls.

The default was reduced from 1000 to 100 for better cost protection. Most agents complete successfully within 100 steps.

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.

Telemetry

AGENTUSE_TELEMETRY_DISABLED

boolean

Disable anonymous telemetry collection. No prompts, code, or file paths are ever collected. Default: false (telemetry enabled)

export AGENTUSE_TELEMETRY_DISABLED=true

Storage

XDG_DATA_HOME

string

Override the default data directory for session logs and project data. Default: ~/.local/share

export XDG_DATA_HOME="/custom/data/path"

Session logs are stored at $XDG_DATA_HOME/agentuse/project/{git-hash}/session/.See Session Logs for more details.

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-5
mcpServers:
  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?

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

Setting Environment Variables

Option 1: .env File (Recommended)
Option 2: Shell Export
Option 3: Inline Command
Option 4: Secret Managers

Create a .env file in your project root:

# .env
NOTION_API_KEY=secret_abc123
GITHUB_TOKEN=ghp_xyz789
OPENAI_API_KEY=sk-proj-...

AgentUse automatically loads .env files from the project root (detected via .git/, .agentuse/, or package.json).Override Options:

# Use a specific .env file
agentuse run agent.agentuse --env-file .env.production

# Run from a different directory
agentuse run agent.agentuse -C /path/to/project

Add .env to your .gitignore to prevent committing secrets!

Export variables in your shell session:

export NOTION_API_KEY="secret_abc123"
export GITHUB_TOKEN="ghp_xyz789"

# Then run your agent
agentuse run my-agent.agentuse

For permanent setup, add to ~/.zshrc or ~/.bashrc:

# ~/.zshrc
export NOTION_API_KEY="secret_abc123"
export GITHUB_TOKEN="ghp_xyz789"

Pass variables directly when running:

NOTION_API_KEY="secret_abc123" agentuse run my-agent.agentuse

Useful for CI/CD or one-time runs.

For production, use secret managers:

# AWS Secrets Manager
export NOTION_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id notion-api-key --query SecretString --output text)

# 1Password CLI
export NOTION_API_KEY=$(op read "op://vault/notion/api-key")

# HashiCorp Vault
export NOTION_API_KEY=$(vault kv get -field=api_key secret/notion)

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-5
mcpServers:
  # 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

# Telemetry (opt-out)
AGENTUSE_TELEMETRY_DISABLED=false

Never commit .env files to version control. Add them to .gitignore.

Priority Order

Environment variables are loaded in this order (later overrides earlier):

System environment variables
.env file in current directory
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)
mcpServers:
  github:
    env:
      GITHUB_TOKEN: "ghp_actualTokenHere"  # Not supported by design!

# ✅ Good - Use environment variable allowlist
mcpServers:
  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

API key not found

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

Wrong API key being used

Check which key is being used:

agentuse auth list

The tool prioritizes OAuth tokens over API keys for Anthropic.

MAX_STEPS not working

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

Getting Started

Building

Running

Reference

Environment Variables

API Configuration

Custom API Key Suffixes

Serve Mode

Behavior Control

Context Management

Logging and Debug

Telemetry

Storage

Development Variables

MCP Server Environment Variables

The Security Model

Why This Design?

Setting Environment Variables

Error Messages

Complete Example

Using .env Files

Priority Order

Security Best Practices

Store Secrets Securely

Use .gitignore

Validate Required Variables

Troubleshooting

Next Steps

Model Configuration

MCP Configuration

Getting Started

Building

Running

Reference

​API Configuration

​Custom API Key Suffixes

​Serve Mode

​Behavior Control

​Context Management

​Logging and Debug

​Telemetry

​Storage

​Development Variables

​MCP Server Environment Variables

​The Security Model

​Why This Design?

​Setting Environment Variables

​Error Messages

​Complete Example

​Using .env Files

​Priority Order

​Security Best Practices

​Store Secrets Securely

​Use .gitignore

​Validate Required Variables

​Troubleshooting

​Next Steps

Model Configuration

MCP Configuration

API Configuration

Custom API Key Suffixes

Serve Mode

Behavior Control

Context Management

Logging and Debug

Telemetry

Storage

Development Variables

MCP Server Environment Variables

The Security Model

Why This Design?

Setting Environment Variables

Error Messages

Complete Example

Using .env Files

Priority Order

Security Best Practices

Store Secrets Securely

Use .gitignore

Validate Required Variables

Troubleshooting

Next Steps