Trust configuration: per-teammate authorization

Configure ~/.agentrelay/trust.yaml to control which teammates can trigger reads, tests, and file writes on your machine, and how unknown senders are handled.

~/.agentrelay/trust.yaml is Layer 3 of AgentRelay’s four-layer trust model. It lives on your laptop and gives you fine-grained control over what each teammate’s agent is pre-authorized to do when you accept one of their handoffs. Layer 2 (the permission overlay written by agentrelay install) sets the floor — trust.yaml lets you selectively raise the ceiling for teammates you trust more.

The file is read by the MCP server every time you accept a handoff. You can edit it directly or manage it through the agentrelay trust CLI.

The safe default for unknown_teammates.policy is reject. With reject, any handoff from a sender not explicitly listed in teammates: is automatically refused — your agent never sees the content. Switch to allow_with_default_trust only when you’re comfortable with the defaults applied to unlisted senders. When in doubt, list teammates explicitly.

---

Full schema

version: 1

# Per-teammate trust overrides.
# Handles are the same identifiers teammates used when they ran `agentrelay register`.
teammates:
  bob@acme:
    auto_read: true              # Bob's handoffs may trigger read operations without prompting you
    auto_test: true              # ...and test/lint runs (sandboxed, no external effects)
    auto_write_paths: []         # no paths pre-authorized for auto-write; every Edit/Write prompts you
    require_approval: ["Edit", "Write", "Bash"]

  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: ["docs/", "README.md"]   # Carol can auto-write to docs only
    require_approval: ["Edit", "Write", "Bash"] # everything outside auto_write_paths still asks you

# What to do when a handoff arrives from a sender not listed in teammates: above.
# 'reject'                  — refuse the handoff immediately (safe default)
# 'allow_with_default_trust' — accept it and apply the values under defaults: below
unknown_teammates:
  policy: "reject"

# Hard block list. Entries here always reject, regardless of any teammates: entry.
# Populated automatically by `agentrelay block <handle>`.
blocked:
  - mallory@external

# Applied to any teammate listed in teammates: that does not override a given field.
# Also applied to unknown senders when policy is allow_with_default_trust.
defaults:
  auto_read: true
  auto_test: true
  auto_write_paths: []

---

Field reference

version

Required. Must be 1. Future schema changes will bump this value and document a migration path.

teammates

A map of teammate handles to per-teammate settings. Each entry can specify:

Field	Type	Description
auto_read	boolean	Allow read-only tool calls (Read, Grep, Glob) without prompting. Defaults to true from defaults:.
auto_test	boolean	Allow sandboxed test and lint runs (npm test, pytest, tsc, etc.) without prompting. Defaults to true from defaults:.
auto_write_paths	string[]	Glob patterns for paths where Edit and Write calls are pre-approved. Empty array means every write prompts you.
require_approval	string[]	Tool names that always require your explicit approval, regardless of auto_write_paths. Typically ["Edit", "Write", "Bash"].

Any field not set for a teammate falls back to the matching value in defaults:.

unknown_teammates

Controls what happens when a handoff arrives from a sender whose handle is not in teammates:.

• reject — The MCP server refuses the handoff and returns an error to the relay. Your agent never sees the content. This is the safe default.
• allow_with_default_trust — The handoff is accepted and the values under defaults: are used as the trust overlay. Use this when onboarding a large team and you want a working baseline before everyone is listed explicitly.

blocked

A list of handles that are hard-blocked. The block is checked before any other rule — a handle in blocked: is always rejected, even if it also appears in teammates:. This list is populated by agentrelay block <handle>. Your MCP server rejects handoffs from blocked handles on every evaluation, before returning any content to your agent.

defaults

Fallback values for any trust field not explicitly set on a teammate entry. Also applied to unknown senders when unknown_teammates.policy is allow_with_default_trust.

---

Glob matching for auto_write_paths

Path patterns are matched as glob prefixes against the file paths passed to Edit and Write tool calls.

• docs/ matches docs/api.md, docs/setup/quickstart.md, and any file under docs/
• README.md matches exactly README.md
• src/api/ matches src/api/users.ts but not src/utils/api.ts
• Patterns do not need a leading /

A useful pattern is to give a trusted documentation teammate like Carol auto-write access to docs/ and README.md, while keeping everything else on ask. This eliminates the approval prompt for low-risk doc updates without opening up source code writes:

teammates:
  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: ["docs/", "README.md"]
    require_approval: ["Edit", "Write", "Bash"]

Carol’s agent can update any file under docs/ or README.md directly. An Edit to src/api/users.ts still prompts you.

---

Strict vs permissive examples

strict.yaml

# Strict — explicit allowlist, all unknown senders rejected.
# Good default for a new team or after a security incident.
version: 1

teammates:
  bob@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: []
    require_approval: ["Edit", "Write", "Bash"]

  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: []
    require_approval: ["Edit", "Write", "Bash"]

unknown_teammates:
  policy: "reject"

blocked: []

defaults:
  auto_read: true
  auto_test: true
  auto_write_paths: []

# Permissive — trusted teammates get auto-write on their domains;
# unknown senders get default trust. Good for a stable, small team.
version: 1

teammates:
  bob@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: ["relay/", "mcp-server/"]
    require_approval: ["Edit", "Write", "Bash"]

  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths: ["docs/", "README.md"]
    require_approval: ["Edit", "Write", "Bash"]

unknown_teammates:
  policy: "allow_with_default_trust"

blocked: []

defaults:
  auto_read: true
  auto_test: true
  auto_write_paths: []
  require_approval: ["Edit", "Write", "Bash"]

---

When to use stricter vs looser settings

Use stricter settings (explicit teammates: entries, unknown_teammates: reject) when:

• Your team is onboarding a new member whose work style you don’t know yet
• You’ve seen unexpected behavior from an agent in a recent handoff
• Your machine holds sensitive data or production credentials
• You’re working on a security-sensitive part of the codebase

Use looser settings (auto_write_paths, allow_with_default_trust) when:

• You’ve worked with a teammate long enough to trust their agent’s scope
• The paths involved are low-risk (documentation, generated files, test fixtures)
• You want to reduce friction for a high-volume, low-risk collaboration pattern

---

Managing trust from the CLI

You can edit trust.yaml directly in any text editor, or use the agentrelay trust subcommands:

# List current trust settings
agentrelay trust list

# Update a teammate's auto_write_paths
agentrelay trust set carol@acme --auto-write-paths "docs/,README.md"

# Reset a teammate back to defaults
agentrelay trust reset carol@acme

Changes take effect immediately — the MCP server reads the file on every handoff acceptance.

---

Blocking a teammate

To immediately revoke a teammate’s ability to reach you:

npx -y -p agentrelay-mcp agentrelay block mallory@external

This adds the handle to blocked: in trust.yaml. Your MCP server will reject any incoming handoff from that sender on the next evaluation. To undo:

npx -y -p agentrelay-mcp agentrelay unblock mallory@external

---

How trust.yaml fits into the four-layer model

Trust configuration is one layer in a defense-in-depth stack. Even the most permissive trust.yaml settings cannot override the layers above or below:

Layer	What it does	Where it runs
L1 — Provenance wrapping	Every inbound message is wrapped with [INBOUND HANDOFF FROM <handle> via AgentRelay] so your agent treats it as data, not commands	MCP server
L2 — Permission overlay	allow / ask / deny rules in Claude Code or Codex settings; git push and npm publish are hard-denied at the harness level regardless of trust.yaml	Claude Code / Codex
L3 — trust.yaml	Per-teammate authorization; controls which actions are pre-approved vs require your confirmation	MCP server
L4 — Audit log and block	Every mutation logged; agentrelay block revokes instantly	Relay + MCP CLI