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

# Quick Start

> Set up AgentUse and run your first agent

## Choose how to start

### macOS Desktop

Download AgentUse from the
[latest GitHub release](https://github.com/agentuse/agentuse/releases/latest),
move it to Applications, and open it. On the Desktop setup screen, choose
whether AgentUse should launch at login and optionally add its bundled CLI
launcher for Terminal. Select **Continue** to enter the guided setup.

The app includes the runtime, so macOS Desktop users do not need to install
Node.js or AgentUse globally.

### Command line

```bash theme={"system"}
npm install -g agentuse
agentuse --version
```

<Info>
  See [Installation](/installation) for pnpm, Bun, Docker, and development setup options.
</Info>

Start the guided Web setup:

```bash theme={"system"}
agentuse setup
```

On Apple silicon Macs you can also choose **Mac app**, which opens the download page; the app bundles its own runtime. Otherwise choose **Browser** for the guided setup. AgentUse opens its Web UI and keeps the
server running in your terminal. Both routes now follow the same onboarding
flow.

<Steps>
  <Step title="Create or attach a project">
    Keep the suggested name, `my-agents`, to create a dedicated project under
    `~/.agentuse/projects/`, or attach an existing project. AgentUse shows the
    full path before anything writes an agent file. For an existing project,
    the guided flow can scan a sanitized, read-only view and suggest recurring
    work grounded in the repository while accounting for agents already there.
  </Step>

  <Step title="Run the sample agent">
    Select **Run sample agent** to see a complete session in the dashboard. The
    sample uses built-in data, needs no provider credentials, and does not
    create an agent file.
  </Step>

  <Step title="Connect a provider">
    In the sample result, select **Create my first agent**. If no provider is
    ready, AgentUse opens the same provider setup used in Preferences before
    any model call or agent file write.
  </Step>

  <Step title="Create your agent">
    Describe what the agent should do, choose a creator model from a connected
    provider, and select **Create agent**. That model is used only to design and
    name a focused agent using AgentUse authoring guidance; it independently
    chooses a suitable runtime model from the connected providers. AgentUse
    validates the generated source, runtime-model choice, and static safety
    guardrails, then performs a separate read-only model review of whether the
    declared tools can support the draft's operations. For example, exact parser
    diagnostics require a callable parser, not just permission to read files.
    Review the draft, request changes if needed, then select **Save agent**.
    This capability review does not execute or test the finished agent, which
    still needs validation before its first real run. A schedule
    proposed by project discovery starts paused until you test and enable it. If
    you prefer to work hands-on, use **Copy prompt to coding agent** instead;
    the prepared handoff carries your task and keeps the existing validation
    workflow as an escape hatch.
  </Step>

  <Step title="Run it">
    When AgentUse detects the new agent, select **Review agent**, review it, and
    start its first real run. If detection takes too long, you can copy the
    prompt again or check manually without leaving onboarding.
  </Step>
</Steps>

<Warning>
  Your coding agent's own login does not authenticate the agents it creates.
  Connect the runtime provider in AgentUse onboarding or Preferences. Do not
  paste API keys, authorization codes, or OAuth callback URLs into coding-agent
  chat.
</Warning>

### Terminal or headless setup

If a browser cannot be opened, use the same setup flow in the terminal:

```bash theme={"system"}
agentuse setup --terminal
```

AgentUse creates and registers the project, prints its full path, and gives you
the exact next steps. The dashboard is optional for this path.

## Create an agent without a coding agent

You do not need Codex, Claude Code, or another coding agent. Complete
`agentuse setup` first, then use the project path shown by setup.

### 1. Configure a runtime provider

```bash theme={"system"}
cd ~/.agentuse/projects/my-agents
agentuse provider list
agentuse provider login
```

Choose a provider in the login prompt, then list its current models:

```bash theme={"system"}
agentuse models <provider>
```

### 2. Write one agent file

Create `agents/hello.agentuse` and replace `<provider>:<model>` with an exact
model ID from the previous command:

```markdown theme={"system"}
---
model: <provider>:<model>
description: Write a friendly greeting
---

Write a short greeting and suggest one useful task you can help with.
```

### 3. Validate and run it

```bash theme={"system"}
agentuse doctor agents/hello.agentuse
agentuse run agents/hello.agentuse
```

To inspect the result later:

```bash theme={"system"}
agentuse sessions
```

## Start AgentUse again

Setup is only required once. Later, start the registered project and Web UI
with:

```bash theme={"system"}
agentuse serve
```

## What's next?

<CardGroup cols={2}>
  <Card title="Creating Agents" icon="file-pen" href="/guides/creating-agents">
    Learn agent syntax and design patterns
  </Card>

  <Card title="Model Configuration" icon="key" href="/guides/model-configuration">
    Configure providers, credentials, and model defaults
  </Card>

  <Card title="Schedules" icon="clock" href="/guides/schedule">
    Run an agent automatically
  </Card>

  <Card title="CLI Commands" icon="terminal" href="/reference/cli-commands">
    Browse all AgentUse commands
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.