AgentUse - Autonomous Agents That Work Without You

API Configuration

These environment variables are required for authenticating with AI providers.

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

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.

string

API key for OpenAI GPT models.

export OPENAI_API_KEY="sk-proj-..."

string

API key for OpenRouter service.

export OPENROUTER_API_KEY="sk-or-v1-..."

string

API key for OpenCode Go open coding models.

export OPENCODE_GO_API_KEY="..."

string

Optional base URL override for OpenCode Go. Defaults to https://opencode.ai/zen/go/v1.

export OPENCODE_GO_BASE_URL="https://opencode.ai/zen/go/v1"

string

AWS access key ID for Amazon Bedrock authentication (SigV4). Used together with AWS_SECRET_ACCESS_KEY and AWS_REGION.

export AWS_ACCESS_KEY_ID="AKIA..."

string

AWS secret access key for Amazon Bedrock authentication (SigV4).

export AWS_SECRET_ACCESS_KEY="..."

string

AWS region for Amazon Bedrock API calls (e.g. us-east-1). Falls back to AWS_DEFAULT_REGION if unset. Required when using Bedrock.

export AWS_REGION="us-east-1"

string

Optional AWS session token for temporary credentials (e.g. STS / assumed roles) when using Amazon Bedrock.

export AWS_SESSION_TOKEN="..."

string

Bedrock API key (Bearer token). When set, used instead of AWS SigV4 authentication.

export AWS_BEARER_TOKEN_BEDROCK="..."

string

AWS named profile from ~/.aws/credentials / ~/.aws/config. Used when no static keys or Bearer token are set: the SDK credential provider chain resolves SSO cache, assumed roles, instance metadata, etc.

export AWS_REGION=eu-west-1
export AWS_PROFILE=my-bedrock-profile

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

Serve Mode

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/api/run \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"agent": "my-agent.agentuse"}'

Approval Gates

string

Slack bot token used to post and update channel messages when channels.slack listens for approval, completion, or failure. The app needs the chat:write bot scope, and the bot must be in the target channel unless you also grant chat:write.public for public channels.

export SLACK_BOT_TOKEN="xoxb-..."

string

Optional Slack app-level token used for Socket Mode approval actions in Slack. Web approval pages and channel-only Slack messages do not require this token. If set, the app-level token needs connections:write; plain thread-reply comments also require Slack message event subscriptions and the relevant channel history scopes.

export SLACK_APP_TOKEN="xapp-..."

string

Default Slack channel id for Slack channels. Agents can override this with channels.slack.channel_id.

export SLACK_APPROVAL_CHANNEL="C0123456789"

string

Fallback public base URL used to build approval review links. Prefer agentuse serve --public-url ... or serve.publicUrl for hosted deployments.

export AGENTUSE_RESUME_PUBLIC_URL="https://agentuse.mycompany.com"

Behavior Control

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.

number

Default timeout in seconds for individual MCP tool calls. Default: 60

export MCP_TOOL_TIMEOUT="120"

Precedence: A server’s toolTimeout in agent YAML overrides this variable; this variable overrides the built-in 60-second default.

Mock Mode (Testing)

Mock all tool outputs with the LLM instead of executing them. Mirror the --mock flags on agentuse run; see Testing with Mocked Tools.

boolean

1 to mock all tool outputs (no real bash/filesystem/MCP/store side effects). Same as --mock. Requires AGENTUSE_MOCK_MODEL.

string

required

Model that generates mock outputs. Required whenever mock mode is on (same as --mock-model). Not defaulted to the agent’s model on purpose: mock fires an LLM call per tool result, and running that on the agent’s premium, rate-limited token caused opaque 429s.Use the lowest-end model you can reach here: mocking only fabricates a plausible tool result, not real reasoning, so a small fast model is plenty and keeps cost and rate-limit pressure low. Good picks: anthropic:claude-haiku-4-5, openai:gpt-5.4-nano, or openrouter:deepseek/deepseek-v4-flash.Set it for one run with --mock-model, or as a global default in the shell, ~/.agentuse/.env, or the env block of ~/.agentuse/config.json. --mock-model overrides whichever source supplies it.

boolean

1 to also mock the await_human approval gate instead of suspending. Same as --mock-approval.

Context Management

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.

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.

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.

number

Minimum active-context size that triggers opportunistic compaction at an approval gate. Default: 64000

export APPROVAL_COMPACTION_MIN_TOKENS="32000"

This is separate from COMPACTION_THRESHOLD: a 64k-token context may be far below a large model’s window, but still expensive to resend after a human approval pause. Set to 0 to disable approval-boundary compaction while keeping normal model-limit compaction enabled.

number

Minimum active-context size that triggers opportunistic compaction between LLM steps after the first tool call. Default: 64000

export STEP_COMPACTION_MIN_TOKENS="128000"

This enables split-turn compaction for long autonomous runs: older context can be summarized before the next model call even when the full model window is not close to exhausted. Set to 0 to disable step-boundary compaction while keeping approval-boundary and model-limit compaction enabled.

Tool Output

Large tool results are re-sent to the model on every subsequent step, so a single oversized output (a big diff, a verbose log, a huge file) inflates input tokens for the rest of the run. These variables cap how much of any one tool result reaches the model. When session storage is available, truncated bash output keeps the full stdout/stderr stream as a session-local tool output artifact; runner-level truncation of other tool results also saves the full raw result and adds a reference to the bounded preview. Defaults match historical behavior, so you only need to set them to tune.

number

Maximum size (in characters) of a single model-facing tool result, also used by the built-in bash stream cap. Output over this limit is truncated to a head + tail slice, dropping the middle, with a marker noting how much was omitted. Default: 30720 (30KB)

export AGENTUSE_TOOL_MAX_OUTPUT_BYTES="61440"  # 60KB

number

Fraction of AGENTUSE_TOOL_MAX_OUTPUT_BYTES kept as the head when truncating; the remainder is kept as the tail. Errors and context often appear early, while the most recent output appears at the end, so both ends are preserved. Default: 0.4 (40% head / 60% tail)

export AGENTUSE_TOOL_OUTPUT_HEAD_RATIO="0.5"  # even split

Must be a decimal between 0 and 1.

number

Default number of lines read_file returns when no explicit limit is given (and the truncation cap for file reads). Default: 2000

export AGENTUSE_TOOL_MAX_LINES="5000"

number

Per-line character cap for read_file output. Longer lines are truncated with a ... (truncated) suffix. Default: 2000

export AGENTUSE_TOOL_MAX_LINE_LENGTH="4000"

Prefer not generating bloat in the first place over raising these caps. For example, use git diff --stat instead of a full git diff of high-churn files. Truncation is a safety net, not a substitute for asking the tool for less.

Logging and Debug

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.

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

boolean

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

export AGENTUSE_TELEMETRY_DISABLED=true

Storage

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

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

For a full overview of user-facing configuration files and directories, see Configuration 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-...
OPENCODE_GO_API_KEY=...
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
APPROVAL_COMPACTION_MIN_TOKENS=64000
STEP_COMPACTION_MIN_TOKENS=64000

# 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

Approval Gates

Behavior Control

Mock Mode (Testing)

Context Management

Tool Output

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

​Approval Gates

​Behavior Control

​Mock Mode (Testing)

​Context Management

​Tool Output

​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

Approval Gates

Behavior Control

Mock Mode (Testing)

Context Management

Tool Output

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