---
name: rungent
description: "Make an existing product agent-native with rungent. Use when asked to add rungent, to make a product agent-native, or to add an in-app agent or assistant, an MCP server, a CLI, skill.md, llms.txt or ⌘K search over an existing HTTP API with an OpenAPI document (any backend stack; React web apps get the dock)."
---

# rungent: make this product agent-native

rungent turns the product's OpenAPI document, with `x-rungent` on the operations agents may use, into an
in-app assistant (the dock), MCP at `/mcp`, a CLI, `/skill.md`, `/llms.txt`, ⌘K search and answers
cited from the product's docs. Every surface acts as the signed-in user, with the user's own
credential and a signed assertion the API verifies. rungent has no rights of its own.

Every page of the docs has a Markdown twin at `https://rungent.acahti.dev/<slug>.md`. Read the twin
named in a step before you write that step's code.

## 1. Install this skill

Save this file in the repository as `.claude/skills/rungent/SKILL.md` (Claude Code) or
`.agents/skills/rungent/SKILL.md` (Codex, Cursor and others), then continue.

## 2. Decide the shape

Read the repository first: the API's framework, how it serves OpenAPI, its auth middleware, and the
web app's root layout.

- **API in JavaScript or TypeScript** (Hono, Express, Workers, Node): embed rungent with `createRungent`
  from `rungent` (`npm install rungent`). Twin: `javascript.md`.
- **API in any other language**: run `rungent serve` beside it (Docker image
  `ghcr.io/rungent/rungent-server`, or `npx rungent serve` on Node 24), and put both behind
  one reverse proxy on the product's origin. Twins: `python.md`, `deploy.md`.
- **Python / FastAPI**: also use the Python kit, `pip install "rungent[fastapi]"`. Twin: `python.md`.
- **Web app in React 19**: add the dock from `rungent/react`. Another framework still gets
  MCP, the CLI, `skill.md` and search; the dock needs React.

If the API has no OpenAPI 3.1 document, add one with the framework's usual generator
(`@hono/zod-openapi`, FastAPI's built-in, springdoc, swag) before anything else.

## 3. Integrate

Do the steps in order. Keep each change small and in the style of the code around it.

### 3.1 Annotate operations (twin: `catalog.md`, keys in `x-rungent.md`)

Add `x-rungent` to the operations the product's own UI uses for what users do day to day. Leave the
rest unannotated: they stay invisible to rungent.

```json
"x-rungent": {
  "name": "stop_vm",
  "description": "Stop a running cloud server (VM).",
  "effect": "update",
  "resolve": { "vm_id": { "op": "list_vms" } },
  "confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vms/{vm_id}", "labelPath": "name" } }
}
```

- **Expose** reads users need (lists, details) and the writes the UI offers them. Do not expose
  admin-only, billing, auth or account-deletion operations, internal or debug routes, or bulk
  destructive operations, unless the developer asks; if they do, keep `approval: always`.
- **`name`**: `snake_case` verb and noun, `^[a-z][a-z0-9_]{0,63}$`, unique (`list_vms`, `stop_vm`).
- **`description`**: written for an agent choosing a tool. Say what it does and name the resource
  with the words users say for it: "Stop a running cloud server (VM)." One sentence, at most 500
  characters.
- **`effect`**: set it when the method does not say it (a `POST /stop` is `update`; a `POST` that
  only searches or computes is `read`; sending mail or charging money is `external`). A `GET` is
  always `read`. Every effect but `read` is a write and waits for the user's approval.
- **`resolve`**: on every id argument that a list operation can resolve from a name, so users can
  say "train-01".
- **`confirmation`**: on every write. `title` is a question; add `lookup` so the card names the
  target, `fields` for arguments that matter, `risk: "high"` for destructive ones.
- **`form`**: on every create or change operation whose page has a form. Add a `role: form`
  operation (a `POST`; rungent treats it as a read) that answers
  `{prompt, questions: [{id, prompt, kind: "text" | "choice", required, options?}]}`, with each
  question's `id` the dotted path of the argument it fills. Twin: `forms-and-approvals.md`.
- **`open`**: the page to show after success, `"/vms/{vm_id}"`.
- **`cli`**: `{"command": "vm stop", "args": ["vm_id"]}` for natural commands.
- **`redact`**: result fields agents must not see. Secret-like keys are removed anyway.
- Search: if the API has a search endpoint, add `{"role": "search"}` on a `GET` with a required
  `q` that answers `{hits: [{type, id, title, url, excerpt?, content?}]}`. Twin: `search.md`.

In FastAPI, write `openapi_extra=op("stop_vm", effect="update", ...)` with `from rungent import op`
(snake case keys). With `@hono/zod-openapi`, put `'x-rungent': {...}` in `createRoute`.

### 3.2 Add the identity operation (twin: `acting-as-the-user.md`)

Exactly one `GET` without parameters, `{"name": "whoami", "role": "identity"}`, answering
`{subject, tenant?, name?, locale?, scopes?}` for the request's own credential, behind the usual
auth middleware. `scopes: ["rungent:admin"]` only for the product's admins.

### 3.3 Serve the catalog behind the user's auth

rungent fetches the OpenAPI document with each user's `Authorization` and `Cookie` headers. Serve it
on a path the auth middleware covers, or publicly if the API is public. It may leave out
operations a user may not call.

### 3.4 Make keys and the secret

```bash
npx rungent keys generate --kid rungent-2026-11 -o rungent-2026-11.private.jwk > rungent-2026-11.public.jwk
openssl rand -base64 48   # RUNGENT_SECRET
```

The private JWK is `RUNGENT_SIGNING_KEY`, for rungent only; the public JWK is `RUNGENT_PUBLIC_JWK`, for the
API. Add both, `RUNGENT_SECRET` and the model key to the project's env example with empty values, add
`*.private.jwk` to `.gitignore`, and never commit a value. For local development an embedded host
may use `(await generateKeyPair('dev')).signing` from `rungent/delegation` and
`new MemoryStore()`.

### 3.5 Mount rungent

Embedded (twin: `javascript.md`):

```ts
import { createRungent, SqlStore } from 'rungent';
import { importSigningKey } from 'rungent/delegation';
import { postgresDriver } from 'rungent/sql/postgres';

const rungent = createRungent({
  url: origin,
  host: { origin, openapi: '/api/openapi.json', fetch: app.fetch },
  signingKey: await importSigningKey(JSON.parse(process.env.RUNGENT_SIGNING_KEY!)),
  secret: process.env.RUNGENT_SECRET!,
  store: new SqlStore(postgresDriver(process.env.DATABASE_URL!)),
  models: { chain: [{ id: 'main', provider: 'openai', model: 'gpt-4.1-mini', apiKey: process.env.OPENAI_API_KEY }] },
});
for (const path of ['/rungent/v0/*', '/mcp', '/skill.md', '/llms.txt', '/.well-known/rungent-keys.json']) {
  app.all(path, (c) => rungent.fetch(c.req.raw));
}
```

Express: `app.all([...paths], nodeHandler(rungent))` from `rungent/node`, registered before
any body parser, with `host.baseUrl` set to the API's loopback address. Workers: build rungent once
per isolate and pass `c.executionCtx`; store `new SqlStore(d1Driver(env.DB))`.

Beside another stack (twin: `deploy.md`): set `RUNGENT_URL`, `RUNGENT_HOST_ORIGIN`, `RUNGENT_SIGNING_KEY`,
`RUNGENT_SECRET`, `RUNGENT_DATABASE_URL` (`postgres://…` or `sqlite:<path>`), and usually
`RUNGENT_HOST_BASE_URL`, `RUNGENT_HOST_OPENAPI` and `RUNGENT_MODELS`. Route `/rungent/v0/*`, `/mcp`,
`/skill.md`, `/llms.txt` and `/.well-known/rungent-keys.json` to rungent with response buffering off;
everything else to the API. Add the service to the project's compose file or deployment
manifests if it has them.

### 3.6 Verify the assertion on every annotated route

Every call from rungent carries `Rungent-Assertion`. A request without it is an ordinary user request.
With it, the API must reject (`401 rungent_assertion_invalid`) unless the signature, audience,
lifetime, method, URL, body hash and replay checks pass, `sub`/`ten` equal the user the request's
own credential authenticates, `op` is the operation serving the route, and `apr` is present for
operations with `approval: always`.

- TypeScript: `verifyAssertion(token, {keys, audience, request: {method, url, body}, remember})`
  then `checkCall(claims, {subject, tenant, op, approval})`, from `rungent/delegation`,
  in a middleware on each annotated route. The quickstart twin (`quickstart.md`) has the whole
  Hono middleware; hash the exact raw body, and build `url` from the public origin.
- FastAPI: `RungentHost(app, keys=load_public_keys([...]), audience=origin, identity=caller)` from
  `rungent.fastapi`, once. Pass `replay_cache` (Redis) when there are several workers.
- Other languages: implement the checks table in `python.md#any-other-language`.

The replay cache must be shared by every process that serves the API. Record `actor = rungent`,
`rid` and `apr` in the audit log where the API has one.

### 3.7 Mount the dock once, in the root layout (twin: `javascript.md#add-the-dock`)

```tsx
import { createClient } from 'rungent/client';
import { RungentDock, RungentProvider, SearchPalette } from 'rungent/react';
import 'rungent/react/styles.css';

const client = createClient();

<RungentProvider client={client} locale={lang} onOpen={navigate} forms={{ create_vm: CreateVmForRungent }}>
  <RungentDock>{children}</RungentDock>
  <SearchPalette />
</RungentProvider>
```

Wrap the area the pages render in, inside the router so `onOpen` can navigate. For each operation
with `form`, register the page's existing form component through a small adapter taking
`HostFormProps` (`arguments` as initial values, `issues` as errors, `submit(args)`, `cancel()`).
Never build a second form. Pass `headers` to `createClient` only if the app sends a bearer token
instead of cookies.

### 3.8 Add the docs as knowledge (twin: `search.md`)

If the repository has Markdown user docs, index them: `RUNGENT_KNOWLEDGE_DIR` and
`RUNGENT_KNOWLEDGE_BASE_URL` with `rungent serve`, or `createKnowledge` from `rungent/knowledge`
with `sources: [knowledge.source({ collections: () => ['docs'] })]` when embedded.

### 3.9 Models (twin: `deploy.md#choose-models`)

Use the provider the project already uses, from env; otherwise `openai` with `OPENAI_API_KEY`.
Put a second endpoint in the chain if one is available. `instructions` (`RUNGENT_INSTRUCTIONS`) may
hold short product facts the API does not say; leave it out otherwise.

## 4. Check it

1. `npx rungent check --openapi <url-or-file>` until it prints `ok`. If the UI's API calls are easy to
   list, pass them with `--routes routes.txt` (`METHOD /path` per line).
2. Run the type checker and the existing tests.
3. Start the app, sign in, and open `/skill.md`: it lists the exposed operations.
4. In the dock (⌘J), ask a question a read answers, then ask for a write: the form or the approval
   card appears, and nothing runs until you approve.
5. Send a request with a forged `Rungent-Assertion` to an annotated route: it must answer `401`.
6. If the project uses Argos, run the rungent contract cases (twin: `testing.md`).

Do what you can run; say what you could not.

## 5. Rules

- Never give rungent a service account, an API key of its own or any extra rights. It acts only with
  the user's credential; the API's permission checks stay unchanged.
- Never put form or approval rules in `instructions`. Approval comes from `effect`/`approval` in
  the catalog and forms from `form`; `instructions` hold product facts only.
- Never expose admin-only or destructive operations without a `confirmation`, and never set
  `approval: never` on a write.
- Keep secrets in the environment or the project's secret store: the signing key, `RUNGENT_SECRET`,
  model keys, database URLs. Never commit them or print them.
- Do not change existing routes' behavior for ordinary requests; the assertion check only adds a
  rejection for bad assertions.

## 6. Report back

Tell the developer, briefly:

- the exposed operations, as a table: name, method and path, effect, approval, form;
- what is left to configure: the signing key and its public half, `RUNGENT_SECRET`, the model key,
  the database, the proxy routes, the knowledge folder;
- how to try it: the command to start the app, then ⌘J in the web app, `/skill.md`, and
  `claude mcp add --transport http <name> <origin>/mcp --header "Authorization: Bearer <token>"`.
