rungent v0.5.1
EN中文

rungentConcepts

Acting as the user

rungent has no account in your product. It calls your API with the signed-in user's own credential and a short-lived signed assertion that names the operation; your API checks both and authorizes the call as it would a click in your UI.

Where people and agents workIn-app assistantthe dock beside your pages⌘K searchresources and docsMCP clientsClaude Code, Cursor, …CLIyour branded commandskill.md · llms.txtfor any agentrungentOne catalogyour OpenAPI, as each user sees itRouting → form → approvalone path for every changeAgent loopmodel chain, retries, limitsThreads and streamingAG-UI events, resumableSearch and knowledgefederated, citedYour productHTTP APIOpenAPI 3.1 + x-rungentIdentitywho is signed inPermissionsyour rules decidePage formsthe same form as your pageDocsanswers cite themthe user'ssessionuser credential+ signed assertionresults,your errorsEvery call runs as the signed-in user. rungent holds no privilege of its own.Where people and agents workIn-app assistantthe dock beside your pages⌘K searchresources and docsMCP clientsClaude Code, Cursor, …CLIyour branded commandskill.md · llms.txtfor any agentthe user'ssessionrungentOne catalogyour OpenAPI, as each user sees itRouting → form → approvalone path for every changeAgent loopmodel chain, retries, limitsThreads and streamingAG-UI events, resumableSearch and knowledgefederated, citeduser credential+ signed assertionYour productHTTP APIOpenAPI 3.1 + x-rungentIdentitywho is signed inPermissionsyour rules decidePage formsthe same form as your pageDocsanswers cite them

Every call runs as the signed-in user. rungent holds no privilege of its own.

When a user approves "Stop server gpu-train-01?", rungent sends your API this request:

POST /api/vms/vm-42/stop HTTP/1.1
Host: console.example.com
Authorization: Bearer <the user's own credential, as rungent received it>
Rungent-Assertion: eyJhbGciOiJFZERTQSIsImtpZCI6InJ1bmdlbnQtMjAyNi0xMSIsInR5cCI6InJ1bmdlbnQtY2FsbCtqd3QifQ…
Content-Type: application/json

{"forced":false}

Your API authenticates the credential as it always does, so the user's own permissions decide what the call may do. The assertion proves the rest: rungent sent this exact request, for this user, for this operation, after the user approved these arguments.

Who the user is#

rungent keeps no user database. It asks your API through the one catalog operation with role: identity, a GET without parameters:

"/api/me": { "get": { "x-rungent": { "name": "whoami", "role": "identity" } } }
{ "subject": "u_123", "tenant": "t_9", "name": "Ada Lovelace", "locale": "zh-CN", "scopes": ["rungent:admin"] }
Field Meaning
subject Required. The user's stable id in your product.
tenant The organization or workspace the credential acts in, when your product has one.
name The display name.
locale A language tag such as en or zh-CN; the assistant answers in it unless the user writes in another.
scopes rungent:admin lets the user change rungent's model settings and read feedback.

rungent calls it with each request's credential, as an ordinary request without an assertion, and remembers the answer for 60 seconds per credential. A 4xx from it makes rungent answer 401. Conversations belong to one (subject, tenant): the same person in two tenants has two histories, and nobody else can read them.

The user's credential#

rungent forwards the request's Authorization and Cookie headers exactly as it received them, and no other header of the user's. In your web app that is the session the user already has, because rungent is served on your own origin. MCP clients and the CLI send a bearer token your API accepts.

rungent holds the credential in memory for the length of a run and never stores it. When it expires mid-run, the call fails with credential_expired, and the user's next message brings a fresh one.

What the assertion binds#

Rungent-Assertion is a compact JWS signed with Ed25519 (alg: EdDSA, typ: rungent-call+jwt, and the signing key's kid). Its claims tie it to one request:

Claim Meaning
iss The rungent instance's URL
aud Your origin, https://console.example.com
sub, ten The user's subject and tenant
op The catalog operation, stop_vm
htm, htu The method, and your public origin followed by the path and query
bsh base64url SHA-256 of the exact body bytes (the empty-body hash when there is none)
apr The approval's id, when the user approved this call
sid, rid, cid The conversation, run and tool call, for your audit log
iat, exp Issued and expires, at most 60 seconds apart
jti A unique id, so the assertion is used once

A stolen assertion is worth very little: it names one method, one URL and one body, lives for a minute, and is accepted once.

Verify the assertion#

A request without Rungent-Assertion is an ordinary user request. With one, your API answers 401 with rungent_assertion_invalid unless all of these hold:

  1. The signature verifies with a rungent public key pinned in your configuration, selected by kid. Never fetch keys from the request.
  2. aud is your origin, exp has not passed (60 seconds of clock skew at most), and jti was not seen before.
  3. htm and bsh match the request as received, and htu is your public origin followed by its path and query.
  4. sub and ten equal the identity you resolved from the request's own credential.
  5. op is the catalog operation that serves this method and path.
  6. When that operation has approval: always, apr is present.

The helpers do it for you. In TypeScript, verifyAssertion runs checks 1 to 3 and checkCall the rest; the Quickstart wraps them in a Hono middleware:

import { checkCall, importPublicKeys, verifyAssertion } from 'rungent/delegation';

const keys = await importPublicKeys([RUNGENT_PUBLIC_JWK]);
const claims = await verifyAssertion(assertion, {
  keys,
  audience: 'https://console.example.com',
  request: { method: 'POST', url: 'https://console.example.com/api/vms/vm-42/stop', body: rawBody },
  remember: (jti, until) => replays.add(jti, until), // false when it was seen before
});
checkCall(claims, { subject: user.id, tenant: user.tenantId, op: 'stop_vm', approval: 'always' });

In FastAPI, RungentHost is one middleware that matches the operation from your routes and runs all six checks; see Python and other stacks, which also covers other languages. Three things are easy to get wrong:

  • The public URL. htu names your public origin even when rungent reaches your API at an internal address. Behind a proxy that strips a path prefix, put the prefix back.
  • One replay cache. Every worker that serves your API must share the record of seen jtis, or a replay may land on a worker that never saw it.
  • Stop at your edge. A gateway that forwards the request to other services removes Rungent-Assertion first; the assertion is for the service that verified it.

Record actor = rungent, rid and apr in your audit log, so every change made through rungent traces back to a run and an approval.

Keys and rotation#

npx rungent keys generate --kid rungent-2026-11 -o rungent-2026-11.private.jwk

It writes the private key, rungent's signing secret, to a new file only you can read, and prints the public JWK for your API's configuration. rungent also serves the public key at /.well-known/rungent-keys.json, for inspection. To rotate:

  1. Generate a key with a new kid.
  2. Add its public JWK to your API, next to the old one, and deploy.
  3. Switch rungent's signing key to the new private key and deploy.
  4. After two minutes (an assertion lives 60 seconds, plus 60 seconds of skew), remove the old public key from your API.

Calls from your API to rungent#

Two calls run the other way: completing a deferred task and a host job (one model completion for your backend, such as a weekly report's summary). Your API signs each with an Rungent-Host-Assertion: the same claims, signed with a key of yours that rungent pins in hostKeys, with aud set to rungent's URL. See HTTP API.

Where to go next#

Forms and approvals shows where apr comes from and what the user sees before it.

For agents: acting-as-the-user.mdEdit this page