How It Works

Airlock has four components that work together: the CLI, the daemon, gate repos, and the desktop app.

Architecture Overview

What airlock init Does

When you run airlock init in a repository:

1. Your current origin remote is renamed to upstream
2. A new gate repository is created locally (a bare Git repo managed by Airlock)
3. origin is set to point at this gate repo
4. A default workflow file is created at .airlock/workflows/main.yml if one doesn't exist

After init, your remotes look like this:

$ git remote -v
origin    /Users/you/.airlock/gates/your-project.git (fetch)
origin    /Users/you/.airlock/gates/your-project.git (push)
upstream  git@github.com:you/your-project.git (fetch)
upstream  git@github.com:you/your-project.git (push)

How a Push Flows

1. You run git push origin feature-branch
2. Git pushes to the local gate repo (fast, since it's on disk)
3. The daemon detects the push and creates a Push Request
4. The daemon checks out a worktree and runs the workflow defined in .airlock/workflows/
5. Each step produces artifacts — content, comments, and patches
6. The Push Request appears in the desktop app with all results
7. You review and click Approve
8. Airlock pushes to upstream and creates a pull request

The Daemon

The Airlock daemon (airlockd) is a background service that watches gate repos for incoming pushes. It:

• Auto-starts via launchd on macOS (installed during brew install --cask airlock)
• Manages worktrees for running workflows
• Executes workflow steps in sequence
• Collects artifacts and builds Push Requests
• Handles the approved push to upstream

Manage the daemon with:

airlock daemon status    # Check if the daemon is running
airlock daemon start     # Start the daemon
airlock daemon stop      # Stop the daemon
airlock daemon restart   # Restart the daemon

The Desktop App

The desktop app is a Tauri application that provides a UI for reviewing Push Requests. Each Push Request has four tabs:

• Overview — PR summary, walk-through, test results and so on
• Changes — Full diff view with inline AI-generated review comments
• Patches — Auto-fix patches from pre-freeze steps (linters, formatters) that you can accept or reject
• Activity — Real-time log of workflow step execution

The CLI

The airlock CLI is used for:

• Setup: airlock init, airlock eject
• Inspection: airlock status, airlock runs, airlock show <id>
• Control: airlock cancel <id>
• Daemon management: airlock daemon start/stop/restart/status
• Diagnostics: airlock doctor, airlock nuke

See the CLI Reference for the complete command list.