AgentUse: Open-source agent runtime

Configuration Profile

string

default:"~/.agentuse"

Directory containing AgentUse’s user-controlled config.json, .env, managed projects/, user-global plugins/, and user-global skills/. Set this together with AGENTUSE_DATA_DIR when isolating a test or development server.

export AGENTUSE_CONFIG_DIR="/tmp/agentuse-test/config"
export AGENTUSE_DATA_DIR="/tmp/agentuse-test/data"

The older AGENTUSE_CONFIG and AGENTUSE_ENV file-level overrides are deprecated compatibility controls. When present they take precedence for their respective file and are scheduled for removal no earlier than December 1, 2026.

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

Claude subscription OAuth is provided by the shortlisted Claude Code Subscription plugin.

string

Long-lived Claude subscription token used by the shortlisted Claude Code Subscription plugin. It is not used by the built-in Anthropic API transport.Install the plugin before using this variable:

agentuse plugins install cb7337/agentuse-claude-code-provider@v0.1.0
export CLAUDE_CODE_OAUTH_TOKEN="your-access-token"

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).The daemon reads it once at startup and removes it from its environment, so bash commands, MCP servers, and skill scripts that agents launch do not inherit it.

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"}'

string

default:"agentuse/agentuse"

GitHub repository (owner/name) that the “Report to AgentUse” link on a changeset review points at. The reviser sets it when a no-change diagnosis blames the AgentUse runtime rather than the agent. Point it at a fork or an internal tracker when your team triages framework bugs elsewhere.

export AGENTUSE_ISSUE_REPO="my-org/agentuse-fork"

number

default:"300"

Heap size, in MB, at which an idle per-project worker is retired and replaced.

export AGENTUSE_WORKER_RECYCLE_MB="300"

A worker bank starts around 130MB of peak heap and settles at roughly 350-450MB once it has executed runs, so a long-lived daemon otherwise holds that memory indefinitely. When an idle worker is over the threshold it is retired through the same release path used at shutdown: runs already in flight finish in the old worker while a replacement starts serving immediately. A worker is only ever recycled while idle, and never within 2 minutes of starting. Set 0 to disable recycling.

string

Set to 0 to restore the old kill-on-shutdown behavior. By default agentuse serve releases its workers on shutdown instead of killing them, so a pm2 or systemd restart does not destroy runs that are mid-flight.

export AGENTUSE_RELEASE_WORKERS="0"

number

Hard deadline, in seconds, for a released worker to exit after the daemon goes away. Defaults to the longest in-flight run’s own timeout plus 10 minutes of grace.

export AGENTUSE_RELEASE_BACKSTOP_SECONDS="1800"

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. Its host also joins the keyless daemon’s allowed request hosts. Prefer agentuse serve --public-url ... or serve.publicUrl for hosted deployments.

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

Behavior Control

string

Model used by agent files that omit model:.

export AGENTUSE_MODEL="anthropic:claude-sonnet"

Accepts anything a model: field accepts: a concrete id, a version alias, a configured @name, or any of those with an :env auth suffix.Precedence: an explicit model: in the agent file wins; otherwise this variable wins over models.default in the AgentUse config. With none of the three set, an agent file without model: fails to parse.

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.

Code Mode

boolean

Code Mode is enabled by default. Set this to 0 to omit code_exec from normal runs. The policy is inherited by recursive subagents and serve worker processes, which makes it suitable for controlled before-and-after tests or emergency rollback. This is a runtime switch only; do not add it to an agent’s frontmatter.

AGENTUSE_CODE_MODE=0 agentuse run agent.agentuse
AGENTUSE_CODE_MODE=0 agentuse serve

The CLI equivalents are agentuse run --no-code-mode and agentuse serve --no-code-mode.

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.

string

What mock mode covers. Unset (or all) mocks every tool result, same as --mock. gated mocks only bash commands matching the agent’s tools.bash.gated patterns and leaves every other tool real, same as agentuse test --scope gated. Only read when mock mode is on.

string

Resolve the await_human approval gate deterministically instead of suspending (mock mode only). Same as --mock-approval. Values: approve (also 1/true), reject, or comment:<text>. An approve grants the gated-command lease from the gate’s changes[] exactly like a real reviewer approval; a reject seals the gate (terminal), and a comment forces the revise-and-re-gate branch on the first gate then approves the re-gate.

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. AgentUse stores oversized direct JSON and text results outside model context and returns a queryable handle instead. Bash keeps a larger bounded canonical capture for that result store, with the complete stream saved as a session artifact if the capture ceiling is crossed.

number

Maximum serialized size of a direct JSON or text response returned inline. Larger results become a reusable resultId handle with a partial preview and jq-style omitted map, and can be narrowed with the results tool. Default: 10240 (10KB)

export AGENTUSE_TOOL_INLINE_RESULT_BYTES="16384"  # 16KB

number

Maximum serialized size returned inline by one results tool query. Queries above this limit ask for a narrower selection and never create another result handle. Default: 20480 (20KB)

export AGENTUSE_RESULT_QUERY_BYTES="32768"  # 32KB

number

Maximum canonical output retained by the built-in bash accumulator for reusable results. Output over this limit is reduced to a head + tail slice and the complete stream is saved as a session artifact; AgentUse does not issue a reusable resultId for that incomplete capture. Default: 4194304 (4MB)

export AGENTUSE_BASH_CAPTURE_BYTES="8388608"  # 8MB

number

Legacy general tool-output limit. It remains the fallback for Bash canonical capture and the inline result limit when their dedicated variables are unset, preserving existing configurations. Prefer AGENTUSE_BASH_CAPTURE_BYTES and AGENTUSE_TOOL_INLINE_RESULT_BYTES for independent control. Default: 30720 (30KB)

export AGENTUSE_TOOL_MAX_OUTPUT_BYTES="61440"  # 60KB

number

Fraction of a truncated output budget kept as the head; 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 all anonymous telemetry, including CLI, daemon, execution, and bundled dashboard telemetry. AgentUse records installation and first-execution lifecycle events, execution metadata, and a fixed top-level dashboard page category. The browser sends that category only to its local AgentUse daemon, which batches delivery; it does not contact PostHog directly. Server telemetry reports only the kind of bind address (host_class: loopback, any, or other), never the host itself. No prompts, code, or file paths are ever collected. Default: false (telemetry enabled)

export AGENTUSE_TELEMETRY_DISABLED=true

Update Checks

boolean

Disable the daily npm registry check and all CLI/Web UI update reminders. Update checks are cached locally, run off the command’s critical path, and are also disabled automatically in CI, local development builds, and npx cache executions. Interactive CLI reminders appear at most once per version every seven days and are suppressed for non-TTY, --quiet, and --json output. The dashboard keeps its dismissal per browser and version.

export AGENTUSE_UPDATE_CHECK_DISABLED=true

Storage

string

default:"~/.local/share/agentuse"

Exact directory containing AgentUse-owned durable data: provider credentials, installed global plugins, sessions, learnings, schedules, server registry and logs, push state, telemetry identity, and update state.

export AGENTUSE_DATA_DIR="/custom/agentuse-data"

AgentUse does not append another agentuse/ component to this path. This variable takes precedence over XDG_DATA_HOME.

string

Standards-compatible fallback base directory. AgentUse uses $XDG_DATA_HOME/agentuse only when AGENTUSE_DATA_DIR is unset. Default XDG base: ~/.local/share.

export XDG_DATA_HOME="/custom/data/path"

Everything a run generates is stored per project, under the resolved AgentUse data directory:

$AGENTUSE_DATA_DIR/project/{git-hash}/
├── session/          # execution logs
├── learnings/        # agent learnings
└── consolidations/   # undo snapshots for `agentuse learnings tidy`

For a fully isolated development daemon, set AGENTUSE_DATA_DIR and AGENTUSE_CONFIG_DIR. Existing XDG-based integrations remain compatible.See Session Logs and Learning 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

When the Claude Code Subscription plugin is installed, subscription OAuth takes priority over the built-in Anthropic API-key transport.

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

Configuration Profile

API Configuration

Custom API Key Suffixes

Serve Mode

Approval Gates

Behavior Control

Code Mode

Mock Mode (Testing)

Context Management

Tool Output

Logging and Debug

Telemetry

Update Checks

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

​Configuration Profile

​API Configuration

​Custom API Key Suffixes

​Serve Mode

​Approval Gates

​Behavior Control

​Code Mode

​Mock Mode (Testing)

​Context Management

​Tool Output

​Logging and Debug

​Telemetry

​Update Checks

​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

Configuration Profile

API Configuration

Custom API Key Suffixes

Serve Mode

Approval Gates

Behavior Control

Code Mode

Mock Mode (Testing)

Context Management

Tool Output

Logging and Debug

Telemetry

Update Checks

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