Airlock

Airlock is a work-in-progress control plane for AI coding agents. It lets tools such as Codex, Claude Code, Cursor-like agents, and desktop AI apps edit local code normally, but routes risky infrastructure actions through a policy checkpoint before developer or workload credentials are used.

The current wedge is simple and concrete: platform teams define agent roles, attach reusable blocked-command policies, and inspect sessions, policy decisions, and audit trails. If a governed agent tries to run a blocked command such as terraform apply, kubectl delete, or aws iam create-role, Airlock blocks before the real executable runs.

Why This Exists

AI coding agents are increasingly allowed to run shell commands, use local credentials, and interact with production-adjacent systems. Prompt instructions alone are not enough for platform engineering teams that need repeatable controls.

Airlock treats agent actions like a production control surface:

• Agent roles define who can use a governed agent profile.
• Reusable policies define blocked command prefixes.
• Local wrappers and shims route protected commands to the Airlock daemon.
• The gateway records deterministic allow/block decisions and audit events.
• Block messages tell the agent to stop instead of retrying, changing PATH, using aliases, or bypassing wrappers.

Architecture

AI coding agent
  -> local wrapper or protected command shim
  -> Airlock daemon
  -> Airlock gateway / admin UI control plane
  -> policy decision
  -> allowed: real tool executes
  -> blocked: audit event + agent instruction

The Airlock Gateway and admin UI are the shared control plane. In production, they are intended to run as normal services, for example in Kubernetes behind company auth and persistent storage. The local daemon exists because a remote service cannot directly intercept command execution on a developer laptop. For development, scripts/dev-up runs the gateway, UI, daemon, and wrappers on one machine.

What Works Today

• Gateway/admin UI that can run locally today and is shaped to become a shared service.
• Local daemon for wrapped agent launches and protected-command checks.
• Codex and Claude Code wrappers that create governed sessions.
• Protected wrappers for tools such as terraform, kubectl, aws, helm, and pulumi.
• Agent roles with attached reusable policies.
• Prefix-based blocked commands such as terraform, terraform plan, or aws iam create-role.
• Session lifecycle tracking for ready/running/exited/revoked sessions.
• Policy decisions and audit trail in the UI.
• Desktop AI support when commands resolve through the Airlock wrapper directory.
• Clear fail-closed behavior for governed agent sessions when the daemon is unavailable.

Current Limits

Airlock is private-WIP software, not a hardened endpoint security product yet.

• Human terminal commands intentionally bypass Airlock in local development.
• Wrapper-only enforcement can be bypassed if a tool calls an absolute real binary, bundled SDK, or direct cloud API.
• Real Okta/OIDC, Vault, GitHub App, AWS, Kubernetes, Terraform Cloud, and production database integrations are modeled but not implemented.
• Credential grants are local/mock grants today.
• Network egress and OS-level process execution monitoring are future hardening work.

Deployment Shape

Airlock has two deployment shapes:

• Shared control plane: Airlock Gateway, admin UI, policy storage, identity integration, and audit storage run as centralized services. Kubernetes is the expected long-term deployment target.
• Developer/workstation client: Airlock daemon, agent wrappers, and protected command wrappers run on the developer machine so local commands can be attributed to the active AI agent session.

The current repository focuses on the local development loop while preserving that split. Localhost ports in this README are development defaults, not a product requirement.

Local Development Quickstart

Start the local gateway, admin UI, daemon, client wrappers, and protected command wrappers:

./scripts/dev-up

Open the admin UI:

http://127.0.0.1:8787

Equivalent module form:

python3 -m airlock.cli.main dev up

Check local state:

python3 -m airlock.cli.main server status
python3 -m airlock.cli.main client status
python3 -m airlock.cli.main daemon status
python3 -m airlock.cli.main sessions list

Switch the default agent role for future governed sessions:

python3 -m airlock.cli.main use terraform-restricted-agent
python3 -m airlock.cli.main current

Run a protected-command smoke test from a governed agent session or known desktop AI app:

which terraform
terraform plan

If the active policy blocks terraform plan, the output should include:

airlock: POLICY BLOCK
airlock: command=terraform plan
airlock: result=blocked; the real executable was not run.
airlock: ai_instruction=Stop. Do not retry this command, call the real binary, change PATH, use sudo, run outside the sandbox, or inspect wrappers to bypass Airlock.

Stop and remove local workstation hooks:

python3 -m airlock.cli.main uninstall --purge-state

Policy Model

Policies are intentionally plain. A reusable policy contains a list of blocked command prefixes:

{
  "blocked_commands": [
    "terraform apply",
    "terraform destroy",
    "kubectl delete",
    "aws iam create-role"
  ],
  "description": "Blocks direct infrastructure mutation commands from governed AI agents.",
  "id": "infra-mutation-block",
  "name": "Infra Mutation Block",
  "rules": [],
  "status": "active"
}

Prefix matching is normalized by executable basename:

• terraform blocks every Terraform subcommand.
• terraform plan blocks terraform plan -out=tfplan, but allows terraform init.
• /opt/homebrew/bin/terraform apply still matches terraform apply.

Agent roles attach one or more reusable policies. The effective blocked command list is the combination of all active attached policies.

Repository Layout

airlock/             Python package for gateway, daemon, CLI, policy, runtime, and local wrappers
web/                 Browser admin UI
policies/            Editable local policy source
docs/                Architecture, runtime, API, and testing docs
docs/assets/         GitHub README graphics and brand assets
docs/diagrams/       Architecture diagrams
tests/               Unit and integration-style tests
scripts/dev-up       One-command local development entrypoint

Development Checks

python3 -m py_compile $(find airlock -name '*.py')
node --check web/app.js
python3 -m unittest discover -s tests -p 'test_*.py'

Docs

• Project status
• Architecture
• Deployment model
• Protected action enforcement
• Runtime flow
• Facts, inventory, and policy
• API and data model
• Local testing guide
• E2E runbook
• Session handoff
• Diagram index

Image Assets

Generated GitHub graphics live here:

• docs/assets/airlock-hero.png
• docs/assets/airlock-logo.png
• docs/assets/policy-gated-agent-actions-badge.png
• docs/diagrams/airlock-architecture.png

Use these paths in GitHub descriptions, README updates, and future social preview work.