Skip to main content

​
System Requirements

Node.js

Version 18.0.0 or higher required

Operating System

macOS, Linux, or Windows with WSL

​
Installation Methods

  • pnpm
  • npm
  • bun
  • yarn
pnpm install -g agentuse

# Verify installation
agentuse --version

​
Run Without Installation

Use pnpx or bunx to run AgentUse without installing: 
# Using pnpx
pnpx agentuse@latest run your-agent.agentuse

# Using npx
npx agentuse@latest run your-agent.agentuse

# Using bunx with Bun runtime (faster)
bunx --bun agentuse run your-agent.agentuse

​
Development Setup

Clone and build from source: 
# Clone the repository
git clone https://github.com/agentuse/agentuse.git
cd agentuse

# Enable corepack if pnpm is not available
corepack enable

# Install dependencies with pnpm
pnpm install

# Build the project
pnpm run build

# Link for local development
pnpm link

# Now you can use 'agentuse' command globally
agentuse --version

​
Authentication Setup

AgentUse supports multiple AI providers. You’ll need to authenticate with at least one: The easiest way to set up authentication: 
# Interactive prompt for all providers
agentuse auth login

# Or login to specific provider
agentuse auth login anthropic
agentuse auth login openai
agentuse auth login openrouter

​
Environment Variables

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

​
Configuration File

Create a .env file in your project root: 
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
OPENROUTER_API_KEY=sk-or-v1-...
Never commit .env files to version control. Add .env to your .gitignore.

​
Verify Installation

Check that everything is working:
1

Check Version

agentuse --version
2

Check Authentication

agentuse auth list
# or use the short alias
agentuse auth ls
3

Run Test Agent

echo '---
name: test
model: anthropic:claude-3-5-haiku-latest
---
Say "Installation successful!"' > test.agentuse

agentuse run test.agentuse

​
Docker Installation

Docker is useful for isolated environments, CI/CD pipelines, or when you want to avoid installing Node.js locally.

​
Development Setup

For local development, mount your project directory to access .agentuse files from the host: 
# Dockerfile.dev
FROM node:20-slim
RUN corepack enable && pnpm install -g agentuse
WORKDIR /app
CMD ["agentuse"]
Build and run with mounted volume: 
# Build the development image
docker build -f Dockerfile.dev -t agentuse-dev .

# Run with your local files mounted
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd):/app \
  agentuse-dev run your-agent.agentuse

​
Production Setup

Include agent files in the image for distribution: 
# Dockerfile.prod
FROM node:20-slim
RUN corepack enable && pnpm install -g agentuse
WORKDIR /app

# Copy your agent files into the container
COPY *.agentuse ./
COPY agents/ ./agents/

# Set default command
ENTRYPOINT ["agentuse", "run"]
CMD ["main.agentuse"]
Build and run: 
# Build with agents included
docker build -f Dockerfile.prod -t my-agent:latest .

# Run without mounting (agents are in the image)
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  my-agent:latest

​
Docker Compose Example

For complex setups with multiple services: 
# docker-compose.yml
version: '3.8'
services:
  agentuse:
    build: .
    environment:
      - ANTHROPIC_API_KEY
      - OPENAI_API_KEY
      - OPENROUTER_API_KEY
    volumes:
      - ./:/app
    command: run main.agentuse
Run with: docker-compose run --rm agentuse

​
Troubleshooting

If agentuse command is not found after installation:
  1. Check your PATH:
echo $PATH
  1. Find where pnpm installs global packages:
pnpm config get prefix
  1. Add to PATH if needed:
export PATH="$PATH:$(pnpm config get prefix)/bin"
Check your Node.js version:
node --version
If below v18, update Node.js:
⌘I