Permissions

Control what workflow agents can read, write, reach over the network, and execute by defining policy in relay.yaml for safe and tightly scoped multi-agent runs.

Permissions in relay.yaml control what each workflow agent can see and do.

If you omit permissions entirely, Relay defaults to inherited dotfiles plus readwrite access.

Quick Start

agents:
  - name: reviewer
    cli: claude
    permissions: readonly

Access Presets

PresetReadWriteDotfiles
readonlyall non-ignorednoneinherited
readwriteall non-ignoredall non-ignoredinherited
restrictednothing (explicit only)nothing (explicit only)inherited
fulleverythingeverythingignored

full bypasses dotfile-based protection. Use only when YAML should be the entire policy surface.

File Permissions

permissions:
  access: restricted
  files:
    read: ['src/**', 'package.json']
    write: ['tests/**']
    deny: ['.env*', 'secrets/**']
  • write implies read access
  • deny always wins over read/write grants
  • Merged on top of the access preset

Network

# Boolean — allow or deny all
permissions:
  network: false

# Object — scoped allowlist
permissions:
  network:
    allow: ['registry.npmjs.org:443', 'github.com:443']
    deny: ['*']

Exec

permissions:
  exec: ['npm test', 'npx vitest', 'git diff']

Matches by command prefix. Omit to allow all commands.

Profiles

Reusable named permission blocks:

permissions:
  profiles:
    source-dev:
      access: restricted
      files:
        read: ['src/**', 'packages/**', 'package.json']
        write: ['src/**', 'tests/**']
        deny: ['.env*', 'secrets/**']
      network: false
  default: source-dev

agents:
  - name: frontend
    cli: codex
    permissions: source-dev

Dotfiles

  • .agentignore — hides files from agents entirely
  • .agentreadonly — visible but not writable
  • .<agent>.agentignore / .<agent>.agentreadonly — per-agent overrides

Applied before YAML rules. Bypassed by full preset.

Resolution Order

  1. Dotfiles (when inherited)
  2. access preset
  3. Explicit files globs
  4. deny rules (always win)

Step-Level Overrides

Steps can narrow the agent's permissions for a specific task:

steps:
  - name: ui
    type: agent
    agent: frontend
    permissions:
      access: restricted
      files:
        write: ['src/components/**']

YAML Reference

agents:
  - name: example
    cli: codex
    permissions:
      access: readonly | readwrite | restricted | full
      inherit: true | false
      files:
        read: ['glob', '...']
        write: ['glob', '...']
        deny: ['glob', '...']
      scopes: ['relayfile:fs:read:/src/**']
      network: true | false | { allow: [...], deny: [...] }
      exec: ['npm test', 'npx vitest']

Dry Run

Validate permissions before a real run:

agent-relay run relay.yaml --dry-run