# Overview

rungent is an open-source framework that makes a product agent-native from the HTTP API it already has. One annotated catalog gives you the in-app agent, MCP, a CLI, a skill, agent-readable docs, global search and cited answers, every one acting as the signed-in user.

## The problem

A product that wants agents to use it ends up building the same thing seven times:

| Surface | Who uses it | Usually built as |
|---|---|---|
| An agent inside the product | your users | a chat widget with its own tool list |
| An MCP server | Claude Code, Cursor, Codex | a second tool list, often on a service account |
| A CLI | developers and their agents | a third copy of the API |
| A skill | coding agents | a hand-written file that drifts |
| Docs agents can read | any agent | `llms.txt`, if anyone remembers |
| Global search | everyone | a separate index of resources |
| Answers from your docs (RAG) | everyone | a separate pipeline with its own model |

Each copy drifts from the API. Each has its own idea of permissions, often broader than the
user's. Writes skip the form your page uses, so an agent asks for different fields than
your UI does, and the same request gets a form one time and a chat interview the next.

## What rungent is

**rungent turns one catalog, your OpenAPI with `x-rungent` on the operations agents may use, into
all seven surfaces, and runs every one of them as the signed-in user.**

Three rules hold on every surface:

- **One catalog.** The agent, MCP tools, CLI commands, skill and search are all generated
  from your operations, so they always say the same thing.
- **One identity.** rungent calls your API with the user's own credential and a signed
  assertion. It has no rights of its own; your permissions decide.
- **One path for changes.** A request to change something opens your page's own form,
  then an approval card bound to the exact arguments, then the call. Never a chat interview.

rungent is one npm package, `rungent`, a server image for non-JavaScript stacks, and a
Python kit. It runs on Node, Bun, Deno and Cloudflare Workers.

## Start with one sentence

Send your coding agent:

```text
Install the rungent skill from https://rungent.acahti.dev/skills/rungent/SKILL.md, then make this product agent-native with it.
```

The skill teaches the agent the whole integration: annotate the operations, add the
identity operation, verify rungent's assertion, mount rungent and the dock, add your docs as
knowledge, and test it. You review a pull request. [Quickstart](quickstart.md) shows what it
writes, if you would rather do it by hand.

Once you ship, your product serves its own `skill.md`, and your users send *their* agents:

```text
Install the skill at https://console.example.com/skill.md and use it to manage my servers.
```

## Two sides, one catalog

rungent has two audiences, and the catalog is where they meet.

*rungent: the build side writes one catalog; the use side gets every surface from it*

- **The build side** is you and your coding agent. You read the [rungent skill](quickstart.md)
  and these docs. You write annotations, one identity operation, one middleware and one
  React component. Nothing else.
- **The use side** is your users and their agents. They never read these docs. They see
  your product: the assistant beside its pages, ⌘K, and the `skill.md`, `/mcp` and CLI it
  serves. Everything they can do is in your catalog, filtered to what they may do.

## How it is built

*rungent between the surfaces people use and your product's API*

rungent sits between the surfaces and your API. It reads your catalog with each user's
credential, runs the agent loop, sends every change through form and approval, streams
the conversation as AG-UI events, and federates search over your resources and docs. Your
product keeps the decisions: identity, permissions, forms and facts. See
[How it works](how-it-works.md).

## Concepts

| Word | Meaning | Page |
|---|---|---|
| Catalog | Your OpenAPI operations marked `x-rungent`, as one user sees them | [The catalog](catalog.md) |
| Identity | Whose request it is; every call is made as that user | [Acting as the user](acting-as-the-user.md) |
| Change path | Route → your form → approval → call | [Forms and approvals](forms-and-approvals.md) |
| Knowledge | Your docs and resources, searched and cited | [Search and knowledge](search.md) |
| Surfaces | Dock, ⌘K, MCP, CLI, `skill.md`, `llms.txt` | [Surfaces](surfaces.md) |

## Where to go next

<ul class="tiles">
<li><a href="quickstart.md"><b>Quickstart</b><span>The one-sentence install, and what it writes into a JavaScript API.</span></a></li>
<li><a href="how-it-works.md"><b>How it works</b><span>The runtime, a request step by step, and the protocol.</span></a></li>
<li><a href="playground.md"><b>Playground</b><span>A sandboxed cloud console that this site's own rungent drives.</span></a></li>
<li><a href="x-rungent.md"><b>Reference</b><span>Every x-rungent key, the HTTP API and the CLI.</span></a></li>
</ul>

> **Version 0.** The protocol is `rungent/0` and the HTTP API lives under `/rungent/v0`; a minor
> release may still break it, and the [changelog](changelog.md) lists every break.
