Guides

Capabilities Guide

Set up what your agent can do — from read-only access to full automation.

Capabilities Guide

Capabilities let you define what your agent is allowed to do at a high level, without micro-managing individual commands. Instead of approving every gh issue comment separately, you grant a capability like "create comments on issues in this repo."

How Capabilities Work

Capability: "gh:issue.comment.create (repo=myorg/app)"
     ↓
Covers any command that matches:
  gh issue comment "some text" --repo myorg/app
  gh issue comment --repo myorg/app "other text"
     ↓
Does NOT cover:
  gh issue close --repo myorg/app        ← different action
  gh issue comment --repo myorg/OTHER    ← different repo

Capabilities are powered by Shapes adapters — each adapter knows how to map CLI commands to structured permissions.

Quick Start

# Install
npm i -g @openape/grapes @openape/shapes

# Install the GitHub CLI adapter
shapes adapter install gh

# Login as agent
grapes login --idp https://id.example.com --key ~/.ssh/agent_key --email agent+reviewer@example.com

Use Case: Agent as PR Reviewer

Grant the agent permission to read PRs and create review comments in a specific repo.

Step 1: See what's available

# What can the gh adapter do?
shapes adapter info gh

# What permissions does a specific command need?
shapes explain -- gh pr review 42 --repo myorg/app --comment --body "LGTM"
# → gh:pr.review (repo=myorg/app, pr=42) — risk: medium

Step 2: Grant review capability

# Grant: create PR reviews in myorg/app (timed, 8 hours)
grapes request-capability gh \
  --resource repo --selector repo.owner=myorg,repo.name=app \
  --action review \
  --approval timed --duration 8h \
  --reason "Daily PR review session" \
  --wait

A human approves the grant. For the next 8 hours, the agent can review any PR in myorg/app.

Step 3: Agent executes

# These all work within the granted capability:
shapes --grant $(grapes token <grant-id>) -- gh pr review 42 --repo myorg/app --comment --body "Looks good"
shapes --grant $(grapes token <grant-id>) -- gh pr review 43 --repo myorg/app --request-changes --body "Fix the tests"

Use Case: Read-Only Monitoring

Grant the agent permission to list and read — but never modify.

# Grant: list and read repos (standing permission)
grapes request-capability gh \
  --resource repo --selector repo.owner=myorg \
  --action list,read \
  --approval always \
  --reason "Continuous monitoring"

Once approved, the agent can:

gh repo list myorg
gh repo view myorg/app
gh issue list --repo myorg/app

But cannot:

gh issue create (action: create)
gh repo delete (action: delete)

Use Case: Issue Triage

Grant the agent permission to label and comment on issues.

# Grant: comment on issues + edit labels in myorg/app
grapes request-capability gh \
  --resource repo --selector repo.owner=myorg,repo.name=app \
  --action comment,edit \
  --approval timed --duration 24h \
  --reason "Issue triage sprint"

The agent can now:

gh issue comment 42 --repo myorg/app --body "Triaged as P2"
gh issue edit 42 --repo myorg/app --add-label "bug"

Use Case: Infrastructure Operations

Grant access to specific Kubernetes namespaces.

# Install the kubectl adapter
shapes adapter install kubectl

# Grant: read pods in production namespace
grapes request-capability kubectl \
  --resource namespace --selector namespace.name=production \
  --resource pod \
  --action list,read \
  --approval always \
  --reason "Production monitoring"

# Grant: restart pods in staging (one-time)
grapes request-capability kubectl \
  --resource namespace --selector namespace.name=staging \
  --resource pod \
  --action delete \
  --approval once \
  --reason "Restart stuck pod"

Use Case: Mail Operations

Grant the agent permission to draft (but not send) emails.

# Install the mail adapter
shapes adapter install o365mail

# Grant: draft emails only
grapes request-capability o365mail \
  --action draft \
  --approval timed --duration 4h \
  --reason "Draft weekly report emails"

The agent can create drafts but cannot send them — sending is a separate action that requires its own grant.

Capability vs. Command Grants

	Capability Grant	Command Grant
Scope	Covers any matching command	Covers one exact command
Example	"read any repo in myorg"	"gh repo view myorg/app"
Flexibility	Agent can operate within bounds	Agent runs exactly one command
Use when	Agent needs ongoing access	One-off operation
Request via	`grapes request-capability`	`grapes request "exact command"`
Matching	Resource chain + action	`cmd_hash` (SHA-256 of exact argv)

Risk Levels and Approval

Shapes adapters define risk levels for each operation. Use these to guide your approval strategy:

Risk	Examples	Recommended Approval
`low`	list, read, view	`always` (standing)
`medium`	create, comment, edit	`timed` (hours/days)
`high`	delete, modify permissions	`once` (single use)
`critical`	drop database, force push	`once` + `exact_command`

# Low risk → standing permission
grapes request-capability gh --action list,read --approval always

# Medium risk → time-limited
grapes request-capability gh --action create,comment --approval timed --duration 8h

# High risk → one-time only
grapes request-capability gh --action delete --approval once

Exploring Available Adapters

# Search the registry
shapes adapter search github
shapes adapter search kubernetes
shapes adapter search mail

# See all remote adapters
shapes adapter list --remote

# After installing, see what operations are available
shapes adapter info gh
shapes adapter info kubectl
shapes adapter info o365mail

Each adapter's operations define exactly which commands map to which permissions. Use shapes explain to check any specific command before requesting a capability.

How It Works

The DDISA login flow and grant system explained.

End-to-End Tutorial

Set up a complete OpenApe environment with IdP, Service Provider, and Agent from scratch.