Airlock

Install

npm install -g airlock-bot

Claude Code setup

Add Airlock as an MCP server in ~/.claude/mcp.json:

{
  "mcpServers": {
    "airlock": {
      "command": "airlock",
      "args": ["--agent", "claude-code", "--config", "/path/to/airlock.yaml"]
    }
  }
}

Or without a global install:

{
  "mcpServers": {
    "airlock": {
      "command": "npx",
      "args": ["airlock-bot", "--agent", "claude-code", "--config", "/path/to/airlock.yaml"]
    }
  }
}

See examples/claude-code-setup.md for a full walkthrough.

Quick start

```bash

Example: safe Python fast path + approved full Python

providers:
  exec: builtin

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

  github_only:
    network:
      allowed_domains:
        - 'github.com'
        - '*.github.com'
        - 'api.github.com'
      denied_domains: []

agents:
  claude-code:
    allow:
      - 'python/sandboxed'
    ask:
      - 'python/full'
      - 'python/github'

    sandbox:
      enabled: true
      presets:
        - local_transform

    tool_overrides:
      python/sandboxed:
        alias_of: 'exec/run'
        description: 'Run Python for local transformations only'

      python/full:
        alias_of: 'exec/run'
        description: 'Run Python with broader permissions after approval'
        sandbox:
          filesystem:
            allow_write:
              - '.'
              - '/tmp'
              - '/private/tmp'
            deny_write: []
          network:
            allowed_domains:
              - 'pypi.org'
              - '*.pythonhosted.org'
            denied_domains: []

      python/github:
        alias_of: 'exec/run'
        description: 'Run Python with GitHub-only network access after approval'
        sandbox_presets:
          - github_only

In this example:

• python/sandboxed inherits the agent's local_transform preset and can be broadly allowed
• python/full keeps the same base tool but overrides filesystem and network to be more permissive, so it should stay in ask
• python/github reuses the same local transform defaults but adds a reusable GitHub-only network preset

2. Create your config referencing the discovered commands

cat > airlock.yaml <<'EOF' providers: github: type: stdio command: npx args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}" exec: builtin http: builtin

clis: git: discovered: ./git-commands.yaml commands: # Inline overrides take precedence over discovered commands status: exec: git status params: {}

agents: claude-code: allow: - github/ - git/ ask: - git/push deny: - exec/run EOF

Configure agent TUI

Interactively assign allow/ask/deny to tools discovered from your live MCP servers:

npm run configure-agent -- --config ./airlock.yaml --agent claude-code

Navigate with j/k, set permissions with a/s/d (per tool or bulk per provider), then Enter to edit config directly, copy to clipboard, or print YAML.

Config

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

exec: builtin http: builtin

1. Discover tools from a CLI you want to expose

airlock discover cli git --output git-commands.yaml

CLI discovery

```bash

API discovery

```bash

Filter endpoints

airlock discover api ./spec.json --include "GET " --exclude "DELETE "

Reference in config:

CLI tools exposed as MCP tools

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

REST APIs exposed as MCP tools

apis: petstore: spec: ./petstore.json base_url: https://petstore.example.com/v1 auth: type: bearer token: ${PETSTORE_TOKEN}

API

When running in gateway mode, Airlock exposes a management API:

GET  /health                   — MCP health, pending HITL count, uptime
GET  /hitl/pending             — list pending approval requests
POST /hitl/approve/:id         — approve a request
POST /hitl/deny/:id            — deny a request (body: {"reason": "..."})
GET  /audit?agent=&tool=&since=&limit=  — query audit log

All management endpoints require Authorization: Bearer <api_secret> when server.api_secret is set.