> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install AgentUse and start deploying autonomous agents

## System Requirements

<CardGroup cols={2}>
  <Card title="Node.js" icon="node">
    Version 18.0.0 or higher required
  </Card>

  <Card title="Operating System" icon="desktop">
    macOS, Linux, or Windows with WSL
  </Card>
</CardGroup>

## Installation Methods

### Global Installation (Recommended)

<Tabs>
  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm install -g agentuse

    # Verify installation
    agentuse --version
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={"system"}
    npm install -g agentuse

    # Verify installation
    agentuse --version
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add -g agentuse

    # Verify installation
    agentuse --version
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn global add agentuse

    # Verify installation
    agentuse --version
    ```
  </Tab>
</Tabs>

### Run Without Installation

Use `pnpx` or `bunx` to run AgentUse without installing:

```bash theme={"system"}
# 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:

```bash theme={"system"}
# 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. Authenticate using the interactive login:

```bash theme={"system"}
agentuse auth login
```

<Card title="Model Configuration" icon="key" href="/guides/model-configuration">
  See the complete authentication guide for OAuth setup, API keys, environment variables, and security best practices.
</Card>

## Verify Installation

Check that everything is working:

<Steps>
  <Step title="Check Version">
    ```bash theme={"system"}
    agentuse --version
    ```
  </Step>

  <Step title="Check Authentication">
    ```bash theme={"system"}
    agentuse auth list
    # or use the short alias
    agentuse auth ls
    ```
  </Step>

  <Step title="Run Test Agent">
    ```bash theme={"system"}
    echo '---
    name: test
    model: anthropic:claude-haiku-4-5
    ---
    Say "Installation successful!"' > test.agentuse

    agentuse run test.agentuse
    ```
  </Step>
</Steps>

## Docker

AgentUse provides an official Docker image with Node.js, Python, and common utilities pre-installed.

<Card title="Self-Hosting" icon="server" href="/guides/self-hosting">
  Run AgentUse in Docker for local development or production deployment.
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found">
    If `agentuse` command is not found after installation:

    1. Check your PATH:

    ```bash theme={"system"}
    echo $PATH
    ```

    2. Find where pnpm installs global packages:

    ```bash theme={"system"}
    pnpm config get prefix
    ```

    3. Add to PATH if needed:

    ```bash theme={"system"}
    export PATH="$PATH:$(pnpm config get prefix)/bin"
    ```
  </Accordion>

  <Accordion title="Node version issues">
    Check your Node.js version:

    ```bash theme={"system"}
    node --version
    ```

    If below v18, update Node.js:

    * Use [nvm](https://github.com/nvm-sh/nvm): `nvm install 20`
    * Or download from [nodejs.org](https://nodejs.org)
  </Accordion>
</AccordionGroup>