Overview
Ecosystem
Agent Gate Applications
Three applications form the core of how agents interact with the world through OpenApe. Together, they ensure that agents can only do what humans have explicitly approved.
┌───────────────────────────────────────────────────┐
│ Agent Gate Applications │
│ │
│ grapes shapes escapes │
│ ──────── ──────── ──────── │
│ Grant System Execution Layer Privilege │
│ Escalation │
│ │
│ Request, approve Execute any CLI, For actions │
│ and manage constrained by the agent │
│ grants grants + registry should never │
│ normally do │
│ │
│ "May I?" "Do it "Exception- │
│ (within bounds)" ally, with │
│ approval" │
└───────────────────────────────────────────────────┘
grapes — The Grant System
The foundation. Without a grant, nothing happens. Grapes handles the complete grant lifecycle: requesting, approving, denying, revoking, and delegating. It's the CLI that both agents and humans use to interact with the OpenApe permission system.
grapes request "systemctl restart nginx" --audience escapes --wait
grapes approve <grant-id>
grapes run escapes "apt-get upgrade" --approval timed --duration 1h
shapes — The Execution Layer
The normal path for agent operations. Shapes wraps existing CLI tools (kubectl, aws, gh, az, etc.) and maps their commands to structured permissions. Instead of granting blanket access, each command is parsed into a resource chain and evaluated against grants.
The Shapes Registry is the catalog of available adapters — it defines which tools can be wrapped and how their commands map to permissions.
shapes explain -- gh repo list myorg # What permissions does this need?
shapes request -- gh issue create --repo myorg/myrepo # Request grant + execute
escapes — Privilege Escalation
The exception path. When an agent needs to do something it should never normally have rights for — installing software for another user, modifying system configuration, accessing restricted resources — escapes provides controlled, audited privilege elevation. Escalated privileges, with apes.
escapes --grant <jwt> -- apt-get install -y nginx
escapes --run-as deploy --grant <jwt> -- systemctl restart app
Agent Infrastructure
Built on top of the gatekeeping trinity. These packages add grant-based access control to specific channels — HTTP traffic and browser automation.
┌───────────────────────────────────────────────────┐
│ Agent Infrastructure │
│ │
│ proxy browser │
│ ───────────── ───────────── │
│ HTTP traffic control Web automation │
│ Grant-based rules Playwright + grants │
│ per domain/method/path + delegation login │
│ │
│ Uses: grants, shapes rules │
└───────────────────────────────────────────────────┘
| Package | Description | Docs |
|---|---|---|
@openape/proxy | Forward proxy — enforces grant-based rules on all agent HTTP traffic | Proxy |
@openape/browser | Headless browser — intercepts routes, enforces grants, supports delegation login | Browser |
Development Packages
Libraries and modules for developers who want to build grant-aware applications. The @openape/grants SDK lets anyone integrate grants into their own apps — not just Nuxt, not just Node.js.
┌───────────────────────────────────────────────────┐
│ Framework Modules │
│ nuxt-auth-idp nuxt-auth-sp │
├───────────────────────────────────────────────────┤
│ Protocol Packages │
│ @openape/auth @openape/grants │
├───────────────────────────────────────────────────┤
│ Foundation │
│ @openape/core │
└───────────────────────────────────────────────────┘
Packages
| Package | Description | Docs |
|---|---|---|
@openape/core | DNS discovery, crypto, PKCE, JWT utilities | — |
@openape/auth | OIDC login protocol — IdP and SP sides | Auth |
@openape/grants | Grant lifecycle, AuthZ-JWT issuance — use this to build grant-aware apps | Grants |
@openape/nuxt-auth-idp | Drop-in Nuxt module: run your own IdP | IdP Config |
@openape/nuxt-auth-sp | Drop-in Nuxt module: login via OpenApe | SP Guide |
Use Cases
| I want to... | Use |
|---|---|
| Add login to my app | nuxt-auth-sp |
| Run my own IdP | nuxt-auth-idp (config) |
| Build grant-aware apps (any framework) | @openape/grants + @openape/auth |
| Control agent HTTP traffic | @openape/proxy |
| Automate browser tasks with grants | @openape/browser |
Design Principles
- Separation — Auth ≠ Grants. Not every app needs both.
- Layered — Core → Protocol → Framework → Agent Tools
- Default deny — No grant = no access. Agents start with zero permissions.
- Passkeys-only — No passwords. NIS2 compliant by design.
- Auditable — Every action traceable: who requested, who approved, what happened.
- Minimal tokens — AuthN says who, AuthZ says what may they do.