Skip to main content

​
Installation

pnpm install -g agentuse
See Installation Guide for npm, bunx, Docker, and development setup options.

​
Authentication

agentuse auth login
See Model Configuration for OAuth setup, API keys, and environment variable configuration.

​
Supported Models

AgentUse supports multiple AI providers with the format provider:model-name. Examples: 
anthropic:claude-sonnet-4-5
openai:gpt-5.2
openrouter:minimax/minimax-m2.1
Any model available from Anthropic, OpenAI, or OpenRouter can be used. You can also specify custom API keys: anthropic:claude-sonnet-4-5:CUSTOM_API_KEY

​
Your First Agent

Create hello.agentuse: 
---
model: anthropic:claude-haiku-4-5
description: "Simple greeting agent that welcomes users"
---

Greet the user.
Run it: 
agentuse run hello.agentuse

# Or run with additional instructions
agentuse run hello.agentuse "speak like a pirate"

# Run with options
agentuse run hello.agentuse --verbose
agentuse run hello.agentuse --quiet
agentuse run hello.agentuse --no-tty
agentuse run hello.agentuse --timeout 600

# Override the model at runtime
agentuse run hello.agentuse --model openai:gpt-5-mini
agentuse run hello.agentuse -m anthropic:claude-sonnet-4-5

​
File System Agent

Create project-analyzer.agentuse: 
---
model: anthropic:claude-haiku-4-5
description: "Analyzes project structure and identifies key components"
mcpServers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
---

You are a code analyzer. When asked about a project:
1. List the main files and folders
2. Identify the project type (Node.js, Python, etc.)
3. Summarize what the project does based on README or package.json
Run it: 
agentuse run project-analyzer.agentuse
See Agent Syntax - MCP Servers for HTTP servers, environment variables, and tool restrictions.

​
Model Override

Override the model at runtime without editing agent files: 
agentuse run analyzer.agentuse --model anthropic:claude-sonnet-4-5
agentuse run analyzer.agentuse -m openai:gpt-5-mini
See CLI Commands - Model Override for format details, environment-specific keys, and sub-agent inheritance behavior.

​
Sub-agents Support

AgentUse supports calling other agents as sub-agents: 
---
model: anthropic:claude-haiku-4-5
description: "Orchestrates tasks by delegating to specialized sub-agents"
subagents:
  - path: "./helper-agent.agentuse"
    name: "helper"
    maxSteps: 50
---

You can call the helper agent using the sub-agent tools.

​
Remote Agents

You can run agents directly from HTTPS URLs: 
# AgentUse will prompt for confirmation before executing remote agents
agentuse run https://example.com/path/to/agent.agentuse

# Preview the agent content first
# Choose 'p' when prompted to preview before execution
Only HTTPS URLs with .agentuse extensions are supported for security. Always review remote agents before execution.

​
Environment Variables

Configure API keys and behavior via environment variables or .env files: 
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
See Environment Variables Reference for all configuration options including custom API key suffixes, behavior control, and MCP server settings.

​
Schedule Your Agent

Add a schedule to run agents automatically: 
---
model: anthropic:claude-sonnet-4-5
schedule: "1h"    # Or cron: "0 * * * *"
---

Check system status and send a summary report.
Start the server to enable scheduling: 
agentuse serve
See Scheduled Agents Guide for cron expressions, intervals, and best practices.

​
What’s Next?

Creating Agents

Learn agent syntax

Examples

See more examples