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

# Local Config Files: config.json and trust.yaml Reference

> Reference for the two AgentRelay config files in ~/.agentrelay/ — credentials in config.json and per-teammate trust policy in trust.yaml, both mode 0600.

AgentRelay stores two configuration files on each developer's laptop under `~/.agentrelay/`. Both files must have mode `0600` (readable only by the owning user) because they contain secrets and per-teammate authorization policy. The `agentrelay register` command creates `config.json` and the `agentrelay install` command creates `trust.yaml` with safe defaults.

<Warning>
  Both files contain secrets. Keep them at mode `0600`. Do not commit them to source control, copy them to shared drives, or let other processes read them. Run `chmod 0600 ~/.agentrelay/config.json ~/.agentrelay/trust.yaml` if the permissions are ever reset.
</Warning>

## `config.json` — credentials and connection

`config.json` stores the credentials the MCP server needs to authenticate with the relay. It is written by `agentrelay register` and read by the MCP server on every startup.

```json theme={null}
{
  "relay_url": "https://relay.acme.dev",
  "agent_handle": "frank@acme",
  "agent_id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
  "api_key": "ah_live_Bx7kR9zYmP4qVnWjL2cDhFsAeT6uXoNr",
  "default_session_id": null
}
```

| Field                | Type           | Description                                                                                             |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `relay_url`          | string         | Base URL of the relay, no trailing slash. Used as the target for all A2A calls.                         |
| `agent_handle`       | string         | Your agent's handle, e.g. `frank@acme`. Used for display and validation.                                |
| `agent_id`           | string         | Your agent's UUID. Used by admin operations like `agentrelay rotate-key`.                               |
| `api_key`            | string         | Your current API key (`ah_live_...` or `ah_test_...`). Sent as the bearer token on every relay request. |
| `default_session_id` | string \| null | Optional session ID to use when accepting handoffs. If null, the MCP server generates one per session.  |

**If `config.json` is missing or unreadable**, the MCP server still starts but every tool call returns an instructive error:

```
Run `agentrelay register` first to connect this agent to a relay.
```

This means you can install the MCP server before registering without breaking your agent harness.

## `trust.yaml` — per-teammate trust policy

`trust.yaml` is Layer 3 of AgentRelay's four-layer trust model. It defines how much autonomy each teammate's agent has on your machine: which action classes run without a prompt, which paths can be written automatically, and which senders are blocked outright.

Created by `agentrelay install` with a default `reject` policy for unknown teammates. Managed by `agentrelay trust` commands or by editing the file directly.

```yaml theme={null}
version: 1

teammates:
  bob@acme:
    auto_read: true              # Bob's handoffs trigger reads with no extra prompt
    auto_test: true              # ...and test runs
    auto_write_paths: []         # ...but no auto-writes
    require_approval: ["Edit", "Write", "Bash"]

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

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

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

defaults:                         # applied to listed teammates if not overridden
  auto_read: true
  auto_test: true
  auto_write_paths: []
```

### Field reference

<ParamField body="version" type="number" required>
  Schema version. Must be `1`. Future schema bumps will document migration steps. Unknown top-level keys produce a warning, not an error.
</ParamField>

<ParamField body="teammates" type="object">
  A map of teammate handles to trust policies. Each key is a handle (`bob@acme`).

  <Expandable title="per-teammate fields">
    <ParamField body="auto_read" type="boolean" default="true">
      If true, read-only tool calls (Read, Grep, Glob) triggered by this teammate's handoffs require no extra prompt.
    </ParamField>

    <ParamField body="auto_test" type="boolean" default="true">
      If true, sandboxed test and lint commands (`npm test*`, `pytest*`, `tsc*`, `cargo test*`, `npm run lint*`) run without a prompt.
    </ParamField>

    <ParamField body="auto_write_paths" type="string[]" default="[]">
      Glob prefixes that this teammate can trigger writes to without approval. For example, `"docs/"` matches `docs/api.md` and `docs/setup/quickstart.md`. Anything outside these paths still follows the `require_approval` rule.
    </ParamField>

    <ParamField body="require_approval" type="string[]">
      Tool classes that always prompt for approval, even for files inside `auto_write_paths`. Defaults to `["Edit", "Write", "Bash"]`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="unknown_teammates" type="object">
  Policy for handoffs from agents not listed in `teammates`.

  <Expandable title="fields">
    <ParamField body="policy" type="string" default="reject">
      `reject` — auto-reject handoffs from unlisted senders (returns `-32013 teammate_blocked`). `allow_with_default_trust` — apply `defaults` to unlisted senders.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="blocked" type="string[]">
  Hard block list. Entries here always reject, regardless of any entry in `teammates`. Populated by `agentrelay block <handle>`. Your MCP server rejects handoffs from these handles on every evaluation.
</ParamField>

<ParamField body="defaults" type="object">
  Fallback policy applied to teammates listed in `teammates` that do not override a specific field. Also applied to unknown teammates when `unknown_teammates.policy` is `allow_with_default_trust`.
</ParamField>

### Glob matching for `auto_write_paths`

Path entries in `auto_write_paths` are matched as glob prefixes. A trailing `/` matches all files under that directory:

* `"docs/"` matches `docs/api.md`, `docs/setup/quickstart.md`, and `docs/reference/components.md`
* `"README.md"` matches only `README.md` at the repo root
* `"src/generated/"` matches any file under `src/generated/`

A sender in the `blocked` list is always rejected even if they are also listed in `teammates` with a permissive policy.

## Environment overrides for testing

Two environment variables let you redirect the MCP server to alternate paths without editing the filesystem:

| Variable                 | Description                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTRELAY_CONFIG_PATH` | Path to an alternate `config.json`. Useful in CI or integration test setups where you want to point the MCP server at a test relay without touching `~/.agentrelay/`. |
| `AGENTRELAY_DEBUG`       | Set to `1` to log all MCP traffic to stderr. Useful for debugging tool call failures.                                                                                 |

These are testing overrides only. In normal operation, use the files in `~/.agentrelay/`.