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

# Managing teammate trust policies and blocking senders

> Use agentrelay trust to manage per-teammate auto-write permissions in trust.yaml, and agentrelay block to prevent a teammate's handoffs from reaching your agent.

The trust model has two CLI-facing levers: `agentrelay trust` for fine-grained per-teammate policies, and `agentrelay block` / `unblock` for immediate revocation. Both operate on `~/.agentrelay/trust.yaml`, which the MCP server reads on every incoming handoff.

## agentrelay trust

The `trust` command provides typed read/write access to `~/.agentrelay/trust.yaml`. You can also edit that file directly with any text editor — the CLI is a convenience layer for scripting and discoverability.

### trust list

Lists all entries in your trust file: explicit teammate policies, the unknown-teammate policy, and the current block list.

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay trust list
```

### trust set

Sets or updates the trust policy for a specific handle. All flags are optional — omitted flags leave the existing value unchanged.

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay trust set <handle> \
  --auto-write-paths "docs/,README.md"
```

| Flag                 | Type                   | Description                                                                                              |
| -------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `--auto-write-paths` | comma-separated string | Glob-prefix paths the agent can write to without prompting you. `docs/` matches all files under `docs/`. |
| `--auto-read`        | boolean                | Allow the agent to perform reads in response to this teammate's handoffs without prompting               |
| `--auto-test`        | boolean                | Allow the agent to run tests in response to this teammate's handoffs without prompting                   |
| `--require-approval` | comma-separated string | Tool names that always require your explicit approval regardless of other settings                       |

For example, to let Carol's agent auto-write documentation files but still ask for approval on everything else:

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay trust set carol@acme \
  --auto-write-paths "docs/,README.md" \
  --auto-read true \
  --auto-test true
```

This produces the following entry in `trust.yaml`:

```yaml theme={null}
teammates:
  carol@acme:
    auto_read: true
    auto_test: true
    auto_write_paths:
      - docs/
      - README.md
    require_approval:
      - Edit
      - Write
      - Bash
```

### trust reset

Removes the explicit entry for a handle, reverting that teammate to the `defaults` policy.

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay trust reset <handle>
```

If the handle is not in the trust file, the command exits without error.

### Editing trust.yaml directly

The file is designed to be human-readable and hand-editable. The CLI only writes when something actually changes, so you retain your formatting on direct edits. The full schema:

```yaml theme={null}
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: ["docs/", "README.md"]
    require_approval: ["Edit", "Write", "Bash"]

unknown_teammates:
  policy: "reject"   # 'reject' | 'allow_with_default_trust'

blocked:             # populated by `agentrelay block`
  - mallory@external

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

`auto_write_paths` entries are matched as glob prefixes — `docs/` matches `docs/api.md` and `docs/setup/quickstart.md`. Setting `unknown_teammates.policy: reject` means any handoff from a handle not listed under `teammates:` is automatically rejected without prompting you.

***

## agentrelay block / unblock

`block` adds a teammate to the `blocked` list in your local `~/.agentrelay/trust.yaml`. When your MCP server processes an incoming handoff, it reads this file and rejects any handoff from a blocked handle before contacting the relay.

<Warning>
  The block takes effect on the next incoming handoff evaluation by your local MCP server. To block a sender at the relay level (so they cannot send even if your MCP server is not running), you can also call `POST /agents/me/block` directly via the relay REST API. See [Admin endpoints](/api/admin-endpoints) for details.
</Warning>

### block

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay block <handle>
```

For example:

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay block mallory@external
```

This adds `mallory@external` to the `blocked: [...]` array in `trust.yaml`. Your MCP server will reject any incoming handoff from that handle on the next evaluation — before returning any content to your agent.

### unblock

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay unblock <handle>
```

Removes the handle from the local `blocked` list in `trust.yaml`. Your MCP server will no longer reject handoffs from that handle on the next evaluation.

### Listing blocks

```bash theme={null}
npx -y -p agentrelay-mcp agentrelay block --list
```

Returns the current block list from your local `trust.yaml`. The `blocked` array is also visible in `agentrelay trust list`.

### How blocks survive restarts

The block list lives in `~/.agentrelay/trust.yaml` under the top-level `blocked:` key. The MCP server reads this file on startup and on each handoff evaluation, so blocks survive process restarts without any additional configuration.

Entries in `blocked:` are a hard override. Even if a handle appears under `teammates:` with explicit trust, a matching entry in `blocked:` always wins — the blocked handle is rejected regardless of any other policy.