Skip to content
RealmrootRealmroot

Quick start

This path starts with the product outcome: an Agent completes a task against a private API without receiving your personal API key.

You need a supported Agent runtime and access to a Realmroot deployment with at least one registered API Resource. When no deployment is specified, the Realmroot Skill uses the hosted production realm at https://id.realmroot.dev.

1. Install the Realmroot Skill

Section titled “1. Install the Realmroot Skill”

Install the Skill globally for your Agent runtime:

Terminal window
npx skills add realmroot/realmroot -g --skill realmroot

For a non-interactive Codex installation:

Terminal window
npx skills add realmroot/realmroot -g --skill realmroot --agent codex -y

Verify the installed source and scope:

Terminal window
npx skills list -g

The Skill contains the current procedures for setting up Restish, establishing identity, discovering resources, requesting access, and invoking the target.

2. Give the Agent a real task

Section titled “2. Give the Agent a real task”

Ask for the result, not the authentication steps:

Use Realmroot to discover and call the private API capability needed to list my active projects.

The Agent will:

  1. resolve the Realmroot deployment and establish its stable identity;
  2. inspect the registered resource catalog;
  3. read candidate APIs’ live OpenAPI contracts;
  4. select the exact operation and least-privilege scopes;
  5. request access when no matching active grant exists;
  6. resume the original operation after approval.

Discovery and approval are intermediate steps. The task is complete only when the target API operation succeeds.

3. Approve the identity and authority boundaries

Section titled “3. Approve the identity and authority boundaries”

On first protected use, Realmroot opens a hosted enrollment page. Sign in as the controller and approve the binding between the current Host and a stable Agent identity.

Enrollment does not grant business API access. When the Agent needs a protected resource, Realmroot presents a separate decision containing:

  • the stable Agent;
  • the API Resource and external account, when applicable;
  • the exact scope set and reason;
  • the requested grant lifetime.

The controller’s browser session makes the decision but never becomes the Agent’s CLI principal.

4. Let the original operation finish

Section titled “4. Let the original operation finish”

After approval, the Restish adapter obtains a short-lived DPoP-bound credential and calls the selected resource URL directly. Raw access tokens, refresh credentials, Host keys, and DPoP private keys stay out of chat and command output.

The API validates the token and request proof, requires the operation’s scopes, and applies its own business rules. Realmroot is not in the business request path.

Run your own realm

Section titled “Run your own realm”

Realmroot is open source and deploys to Cloudflare. Each deployment is one identity and policy realm. Follow Deploy Realmroot to create a deployment, complete first-admin onboarding, and plan upgrades.

Product applications can then register as OIDC clients. API teams can make an API Agent-ready by registering its protected resource URL and live OpenAPI contract.

Next

Section titled “Next”