> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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.
</Warning>

***

## Full schema

```yaml theme={null}
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 `/`

<Tip>
  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:

  ```yaml theme={null}
  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.
</Tip>

***

## Strict vs permissive examples

<CodeGroup>
  ```yaml strict.yaml theme={null}
  # 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: []
  ```

  ```yaml permissive.yaml theme={null}
  # 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"]
  ```
</CodeGroup>

***

## 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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     |