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.

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.

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.

{
  "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.

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

version · number · required

Schema version. Must be 1. Future schema bumps will document migration steps. Unknown top-level keys produce a warning, not an error.

teammates · object

A map of teammate handles to trust policies. Each key is a handle (bob@acme).

Show per-teammate fields

auto_read · boolean · default: "true"

If true, read-only tool calls (Read, Grep, Glob) triggered by this teammate’s handoffs require no extra prompt.

auto_test · boolean · default: "true"

If true, sandboxed test and lint commands (npm test*, pytest*, tsc*, cargo test*, npm run lint*) run without a prompt.

auto_write_paths · 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.

require_approval · string[]

Tool classes that always prompt for approval, even for files inside auto_write_paths. Defaults to ["Edit", "Write", "Bash"].

unknown_teammates · object

Policy for handoffs from agents not listed in teammates.

Show fields

policy · string · default: "reject"

reject — auto-reject handoffs from unlisted senders (returns -32013 teammate_blocked). allow_with_default_trust — apply defaults to unlisted senders.

blocked · 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.

defaults · 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.

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