# Run an agent

Canonical: https://auggy.dev/docs/quickstart
Status: Published
Package: auggy 0.5.0

Create a local **Auggy** agent and complete the first model turn.

## Before you start

- Node.js 20 or newer for the npm package.
- **Bun** 1.2 or newer for the generated agent project.
- An API key for a hosted model provider, or a running Ollama instance.

## Create an agent

**Install and scaffold**

```bash
npm i -g auggy
auggy create my-agent
cd my-agent
```

The create flow asks for the agent name, purpose, provider, and model, then writes a runnable **Bun** project.

## Add the provider credential

Open .env and set the variable named in .env.example. Provider keys belong in .env, never in agent.yaml, skills, memory, or application code.

**.env example for Anthropic**

```env
ANTHROPIC_API_KEY=sk-ant-...
```

## Start the runtime

**Validate and run**

```bash
auggy doctor
auggy run
```

doctor validates the project and provider configuration. run starts the runtime and opens creator chat.

**Run output**

```
Agent "my-agent" is live.

  Chat:     http://localhost:8080/console/chat
  Console:  http://localhost:8080/console
  Health:   http://localhost:8080/health
  Home:     http://localhost:8080/
```

## Verify the first turn

1. Open the printed Chat URL and send: Who are you, and what can you do?
2. Confirm the reply reflects the name and purpose selected during create.
3. If the turn fails, read the foreground terminal, correct the reported provider or configuration error, and rerun `auggy doctor`.

## What just started

| Part | What it did |
| --- | --- |
| Runtime kernel | Loaded the project and completed the model turn. |
| Model provider | Resolved the configured adapter and model client. |
| Web transport | Served chat, console, health, and the agent runtime endpoint. |
| Console | Provided the local creator surface for chat and runtime inspection. |

## Next: add a capability

| Continue | Outcome |
| --- | --- |
| [Add an augment](https://auggy.dev/docs/add-augment/markdown) | Install peer-scoped memory and see how an augment extends the running agent. |

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Model provider](https://auggy.dev/docs/engines/markdown)
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown)