Reference

Proxy Config

TOML configuration reference for the OpenApe agent proxy.

Proxy Configuration

The @openape/proxy reads its configuration from a TOML file. Two formats are supported: single-agent and multi-agent.

Single-Agent Configuration

[proxy]
listen = "127.0.0.1:9090"
idp_url = "https://id.example.com"
agent_email = "agent+bot@example.com"
default_action = "block"
audit_log = "/var/log/openape-proxy/audit.jsonl"

[[allow]]
domain = "api.github.com"
methods = ["GET"]

[[deny]]
domain = "*.internal.corp"

[[grant_required]]
domain = "api.github.com"
methods = ["POST", "PUT", "DELETE"]
grant_type = "once"

`[proxy]` Section

Field	Type	Required	Default	Description
`listen`	`string`	Yes	—	Bind address and port (e.g., `"127.0.0.1:9090"`)
`idp_url`	`string`	Yes	—	IdP URL for grant requests
`agent_email`	`string`	Yes	—	Agent identity email
`default_action`	`string`	Yes	—	Action for unmatched requests: `block`, `request`, `request-async`
`audit_log`	`string`	No	—	Path for JSONL audit log
`mandatory_auth`	`boolean`	No	`false`	Require all requests to carry agent auth

Default Actions

Action	Behavior
`block`	Reject unmatched requests with 403
`request`	Auto-request a grant and block until approved
`request-async`	Auto-request a grant, reject current request, retry on next attempt

Multi-Agent Configuration

[proxy]
listen = "127.0.0.1:9090"
default_action = "block"
audit_log = "/var/log/openape-proxy/audit.jsonl"

[[agents]]
email = "agent+deploy@example.com"
idp_url = "https://id.example.com"

  [[agents.allow]]
  domain = "api.github.com"
  methods = ["GET", "POST"]

  [[agents.grant_required]]
  domain = "api.github.com"
  methods = ["DELETE"]
  grant_type = "once"

[[agents]]
email = "agent+monitor@example.com"
idp_url = "https://id.example.com"

  [[agents.allow]]
  domain = "api.datadog.com"

`[[agents]]` Section

Field	Type	Required	Description
`email`	`string`	Yes	Agent identity email
`idp_url`	`string`	Yes	IdP URL for this agent
`allow`	`RuleEntry[]`	No	Agent-specific allow rules
`deny`	`RuleEntry[]`	No	Agent-specific deny rules
`grant_required`	`GrantRuleEntry[]`	No	Agent-specific grant rules

Rule Entries

`[[allow]]` and `[[deny]]`

Field	Type	Required	Description
`domain`	`string`	Yes	Target domain (supports `*` wildcard)
`methods`	`string[]`	No	HTTP methods (default: all)
`path`	`string`	No	URL path pattern (supports `*` wildcard)
`note`	`string`	No	Documentation note

`[[grant_required]]`

All fields from [[allow]] / [[deny]], plus:

Field	Type	Required	Description
`grant_type`	`string`	Yes	`once`, `timed`, or `always`
`permissions`	`string[]`	No	Required permissions
`duration`	`number`	No	Grant duration in seconds (for `timed`)

Rule Evaluation Order

deny rules are checked first — if matched, request is blocked
allow rules — if matched, request is forwarded
grant_required rules — if matched, a grant must be approved
default_action — applied when no rule matches

Domain Patterns

Pattern	Matches
`api.github.com`	Exact match
`*.github.com`	Any subdomain of github.com
`*`	Any domain

Audit Log Format

Each entry is a single JSON line:

{
  "ts": "2025-01-15T10:30:00.123Z",
  "agent": "agent+deploy@example.com",
  "action": "allow",
  "domain": "api.github.com",
  "method": "GET",
  "path": "/repos/org/repo",
  "grant_id": null,
  "rule": "allow[0]",
  "waited_ms": 0
}

Audit Actions

Action	Description
`allow`	Request was allowed by an allow rule
`deny`	Request was blocked by a deny rule or default action
`grant_approved`	Grant was requested and approved
`grant_denied`	Grant was requested but denied
`grant_timeout`	Grant was requested but timed out
`error`	An error occurred during rule evaluation

CLI Flags

Flag	Description
`--config <path>`	Path to TOML config file (required)
`--dry-run`	Evaluate rules and log decisions, but forward all requests
`--mandatory-auth`	Require agent authentication for all requests

escapes Config

Configuration reference for /etc/openape/config.toml.

Operations

Deployment, monitoring, and troubleshooting for production environments.