# Auggy

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

Build self-hosted agents from a small turn runtime and composable augments.

## A small runtime for self-hosted agents

**Auggy** is a **Bun** and TypeScript runtime for building self-hosted agents. The kernel runs model turns; augments add tools, memory, context, transports, skills, policy, and integrations around those turns.

**One turn**

```
inbound message
  -> transport identifies the peer
  -> augments contribute context and memory
  -> kernel calls the configured model
  -> model requests typed tools when needed
  -> kernel validates and executes tool calls
  -> transport returns the result
```

Agent projects remain ordinary files and TypeScript. Start with a working local agent, install only the capabilities it needs, and keep your frontend, database, auth provider, job system, and existing services in their current stack.

## Build one complete agent

| Step | Outcome |
| --- | --- |
| [1. Run an agent](https://auggy.dev/docs/quickstart/markdown) | Create a local agent, connect a model provider, and complete the first turn. |
| [2. Add an augment](https://auggy.dev/docs/add-augment/markdown) | Install peer-scoped memory and verify it without writing runtime code. |
| [3. Build an augment](https://auggy.dev/docs/build-augment/markdown) | Give the agent one project-specific typed tool. |
| [4. Deploy and verify](https://auggy.dev/docs/deploy/markdown) | Ship the agent runtime and verify its production health and logs. |

## The runtime in one minute

| Part | Job |
| --- | --- |
| Agent | A portable project with identity, model configuration, skills, and enabled augments. |
| Kernel | Runs model turns, tool execution, context, history, and runtime policy. |
| Augment | Adds a coherent runtime capability without changing the kernel. |
| Tool | A typed function the model can request during a turn. |
| Skill | Optional workflow guidance read when tool descriptions are not enough. |
| Knowledge | Reference material fetched only when it is relevant. |

## Choose the right abstraction

| Choose | Use it when | Examples |
| --- | --- | --- |
| Skill or knowledge | The agent needs teaching or reference material, not new runtime behavior. | Playbooks, examples, policies, product facts, and FAQs. |
| Built-in augment | A supported optional capability already fits the job. | Memory, knowledge, MCP, Telegram, notifications, or visitor recognition. |
| Custom augment | The agent needs a new typed tool, integration, context source, policy, lifecycle hook, or transport. | Project-specific support lookup, reporting, escalation, or service integration. |

> **Note: Current operational boundary**
>
> **Auggy** is turn-oriented today. Keep durable jobs, resumable workflows, artifact pipelines, and authenticated approval records in application infrastructure until the runtime provides explicit primitives for them. Optional augment routes and delegated app authorization are available as advanced preview integrations.

## Related

- [Run an agent](https://auggy.dev/docs/quickstart/markdown)
- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Build an augment](https://auggy.dev/docs/build-augment/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)