Config Reference

Airlock config is YAML. Everything lives in a single file (typically airlock.yaml). The config hot-reloads on save — no restart needed.

Top-level sections

providers: # MCP servers and built-ins
profiles: # Reusable permission sets
sandbox_presets: # Reusable sandbox envelopes
clis: # CLI tools exposed as MCP tools
apis: # REST APIs exposed as MCP tools
agents: # Per-agent policy and config
approvals: # Global approval provider config
middleware: # Middleware pipeline config
security: # Host blocking, domain allowlists
audit: # Audit log settings
server: # Gateway server settings

providers

Declares upstream tool sources.

providers:
  # MCP server over stdio
  github:
    type: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: '${GITHUB_TOKEN}'

  # MCP server over SSE
  remote:
    type: sse
    url: https://tools.example.com/sse
    headers:
      Authorization: 'Bearer ${TOKEN}'

  # MCP server over streamable HTTP (with optional OAuth)
  cloud:
    type: http
    url: https://mcp.example.com
    oauth: true
    client_id: ${CLIENT_ID}
    client_secret: ${CLIENT_SECRET}
    oauth_callback_port: 9876

  # Built-ins
  exec: builtin
  http: builtin
  python: builtin

profiles

Reusable permission sets. See Composable Profiles.

profiles:
  readonly:
    allow:
      - '*/list*'
      - '*/get*'
      - http/get
  developer:
    allow:
      - github/*
      - git/*
    ask:
      - github/create_pr

sandbox_presets

Reusable sandbox envelopes. See Sandboxing.

sandbox_presets:
  local_transform:
    filesystem:
      allow_read: ['.']
      allow_write: ['/tmp']
      deny_read: ['~/.ssh', '~/.aws', '.env']
      deny_write: ['.']
    network:
      allowed_domains: []
      denied_domains: []

clis

CLI tools exposed as named MCP tools. See CLI Discovery.

clis:
  git:
    discovered: ./git-commands.yaml
    shell: /bin/bash
    max_output_bytes: 30000
    commands:
      status:
        exec: git status
        params: {}
      log:
        exec: 'git log --oneline -n {count}'
        params:
          count:
            type: number
            required: false
            default: 10

apis

REST APIs exposed as MCP tools. See API Discovery.

apis:
  petstore:
    spec: ./petstore.json
    base_url: https://petstore.example.com/v1
    auth:
      type: bearer # or "basic"
      token: ${TOKEN}
    timeout_ms: 30000
    max_response_bytes: 1048576

agents

Per-agent policy configuration.

agents:
  claude-code:
    extends: [readonly, developer] # Inherit from profiles
    allow:
      - github/*
    ask:
      - github/create_pr
    deny:
      - exec/run

    exec: # Shell command sub-policy
      allow: ['git status', 'npm test*']
      ask: ['git push*']
      deny: ['sudo *', 'rm -rf *']
      env:
        PATH: '/usr/local/bin:/usr/bin:/bin'

    http: # HTTP domain restrictions
      domain_allowlist: ['api.github.com', '*.sentry.io']

    sandbox: # Agent-level sandbox
      enabled: true
      presets: [local_transform]

    tool_overrides: # Tool variants
      python/sandboxed:
        alias_of: exec/run
        description: 'Sandboxed Python'
        sandbox_presets: [local_transform]

approvals

Global approval provider config. See HITL Providers.

approvals:
  provider:
    type: telegram
    bot_token: '${TELEGRAM_BOT_TOKEN}'
    chat_id: '${TELEGRAM_CHAT_ID}'
  timeout_ms: 300000
  batch_window_ms: 10000

middleware

Middleware pipeline config. See Middleware Pipeline.

middleware:
  injection_detector:
    backend: regex
    mode: escalate

  sensitivity_classifier:
    mode: detect
    threshold: 0.7

  canary_tokens: true

  output_injection:
    mode: mangle

  untrusted_envelope: true

  rate_limiter:
    max_requests: 100
    window_ms: 60000
    per: agent

  output_size_limiter:
    max_lines: 200
    max_chars: 30000

  output_summarizer:
    model: claude-haiku-4-5-20251001
    threshold_chars: 10000

security

Host blocking for built-in HTTP tools.

security:
  blocked_hosts:
    - '127.0.0.1'
    - '::1'
    - 'localhost'
    - '10.*'
    - '192.168.*'
    - '172.16.*'
    - '169.254.*'
  allowed_local:
    - 'host.docker.internal'

audit

Audit log settings.

audit:
  redact_fields:
    - password
    - token
    - secret
    - authorization
    - api_key

server

Gateway server settings (used in non-stdio mode).

server:
  port: 4111
  api_secret: '${AIRLOCK_API_SECRET}'

Environment variable substitution

Any value of the form ${VAR_NAME} is replaced with the corresponding environment variable at config load time. This works for all string values in the config.

Example configs

• examples/gateway.yaml — fully annotated reference config
• examples/profiles.yaml — composable profile examples
• examples/sandbox-presets.yaml — sandbox preset and tool variant examples
• examples/local-dev.yaml — minimal local development config