Skip to main content

​
Overview

AgentUse supports multiple AI providers. You need to authenticate with at least one provider to run agents.

​
Supported Providers

Anthropic

Claude models (Opus, Sonnet, Haiku) Supports OAuth and API keys

OpenAI

GPT models including GPT-5, GPT-4, GPT-4o, GPT-3.5 API key authentication

OpenRouter

Access to 100+ models via unified API API key authentication

​
Authentication Methods

The simplest way to authenticate: 
# Interactive menu
agentuse auth login

# Or login to specific provider
agentuse auth login anthropic
agentuse auth login openai
agentuse auth login openrouter
Anthropic supports OAuth login for both Claude Max and Console users - no API key needed!

​
2. Environment Variables

Set API keys as environment variables: 
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."
export OPENROUTER_API_KEY="sk-or-v1-..."

​
3. Configuration File

Create a .env file in your project: 
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
OPENROUTER_API_KEY=sk-or-v1-...

​
Advanced Environment Variable Configuration

AgentUse supports flexible environment variable patterns for multiple API keys: 
# Using environment suffixes for different keys
export ANTHROPIC_API_KEY_DEV=sk-ant-api03-dev-key
export ANTHROPIC_API_KEY_PROD=sk-ant-api03-prod-key
export OPENAI_API_KEY_PERSONAL=sk-proj-personal-key

# Then specify in model string
agentuse run agent.md --model anthropic:claude-sonnet-4-5:dev
agentuse run agent.md --model openai:gpt-5.2:OPENAI_API_KEY_PERSONAL
Never commit .env files to version control! Add to .gitignore:
.env
.env.local
.env.*.local

​
Managing Credentials

​
List Stored Credentials

agentuse auth list
Output: 
📁 Credentials stored in: ~/.local/share/agentuse/auth.json

Stored credentials:
  🔑 anthropic (oauth) → Use as: anthropic:claude-sonnet-4-5
  🎫 openai (api) → Use as: openai:gpt-5.2

Environment variables:
  🌍 openrouter (OPENROUTER_API_KEY) → Use as: openrouter:z-ai/glm-4.7

​
Remove Credentials

# Remove specific provider
agentuse auth logout anthropic

# Remove all credentials
agentuse auth logout

​
Rotate API Keys

# Logout and login again
agentuse auth logout openai
agentuse auth login openai

​
OAuth Authentication (Anthropic)

Both Claude Max and Console users can use OAuth for seamless authentication:
1

Run OAuth Login

agentuse auth login anthropic
Select from:
  • Claude Pro/Max Plan (OAuth) - For claude.ai users
  • Anthropic Console (OAuth) - For console.anthropic.com users
  • Manual API Key - Traditional API key method
2

Authorization URL

Copy the authorization URL shown in terminal and visit in your browser
3

Authorize

Sign in and click “Authorize” to grant AgentUse access
4

Copy Code

Copy the authorization code from the browser
5

Paste Code

Paste the code in terminal - you’re authenticated!

​
OAuth Benefits

  • No API key management required
  • Automatic token refresh
  • Secure PKCE authentication flow
  • Works with both Claude Max and Console accounts
  • Tokens stored securely in ~/.local/share/agentuse/auth.json with restricted permissions

​
API Key Authentication

​
Getting API Keys

Get API keys from provider consoles:
Keys are shown only once. Store them securely and never commit to version control.

​
Authentication Priority Order

AgentUse checks authentication sources in this order:
  1. OAuth tokens (Anthropic only) - Checked first and refreshed automatically
  2. Stored API keys (via agentuse auth login) - Stored in ~/.local/share/agentuse/auth.json
  3. Environment variables - ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY
  4. Custom environment variables - Using suffix patterns (e.g., ANTHROPIC_API_KEY_DEV) or full variable names

​
Security Best Practices

OAuth is more secure than API keys as tokens can be revoked and rotated automatically. AgentUse uses PKCE flow for enhanced security.
Stored credentials in ~/.local/share/agentuse/auth.json are automatically set to user read/write only (0600 permissions).
Change API keys every 90 days or immediately if compromised.
Create keys with minimal required permissions.
Never hardcode keys in your agent files or code.
Regularly check API usage to detect unusual activity.

​
Runtime Model Override

Override the model at runtime using the --model flag: 
agentuse run agent.agentuse --model anthropic:claude-haiku-4-5
agentuse run agent.agentuse -m openai:gpt-5-mini

CLI Commands - Model Override

See the complete reference for model override format, environment-specific keys, CI/CD examples, and sub-agent inheritance behavior.

​
Multi-Provider Setup

Use different providers for different agents: 
---
name: fast-agent
model: anthropic:claude-haiku-4-5  # Uses Anthropic
---

---
name: powerful-agent
model: openai:gpt-5  # Uses OpenAI GPT-5
openai:
  reasoningEffort: high    # More thorough reasoning
  textVerbosity: medium    # Balanced response length
---

---
name: specialized-agent
model: openrouter:z-ai/glm-4.7  # Uses OpenRouter
---

​
Provider Options

Configure provider-specific settings for fine-tuned model behavior:

​
OpenAI Provider Options

For OpenAI models (especially GPT-5), you can control reasoning and verbosity: 
---
model: openai:gpt-5
openai:
  reasoningEffort: high  # Options: 'low', 'medium', 'high'
  textVerbosity: low     # Options: 'low', 'medium', 'high'
---
reasoningEffort: Controls computational effort for reasoning
  • low: Faster responses with less thorough reasoning
  • medium: Balanced performance (default)
  • high: More comprehensive reasoning, slower responses
textVerbosity: Controls response length and detail
  • low: Concise, minimal prose
  • medium: Balanced detail (default)
  • high: Verbose, detailed explanations
These options help you optimize for:
  • Speed vs Quality: Lower reasoning effort for faster responses
  • Conciseness vs Detail: Lower verbosity for more direct answers
  • Cost Optimization: Lower settings reduce token usage

​
Troubleshooting

  • Verify API key is correct
  • Check key hasn’t expired
  • Ensure key has required permissions
  • Try logging out and back in
  • Check your API tier and limits
  • Implement exponential backoff
  • Consider upgrading your plan
  • Use different keys for different projects
  • Clear browser cookies
  • Try a different browser
  • Ensure you’re using the correct OAuth mode (Max vs Console)
  • Check that your Claude subscription is active (for Max mode)
  • Verify you have console access (for Console mode)
  • Try manual API key authentication as fallback

​
CI/CD Authentication

For automated environments:

​
GitHub Actions

name: Run Agent
on: [push]
jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: pnpm install -g agentuse
      - run: agentuse run my-agent.agentuse
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

​
Docker

FROM node:20
RUN npm install -g pnpm && pnpm install -g agentuse
ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ENV OPENAI_API_KEY=${OPENAI_API_KEY}
ENV OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
CMD ["agentuse", "run", "agent.agentuse"]

​
Next Steps

Quick Start

Start using your authenticated providers

Creating Agents

Build agents with your providers