Airlock

Airlock coordinates 1Password-backed secret workflows for coding agents while keeping secret values out of the normal control path.

[!IMPORTANT] Airlock is a pre-1.0, single-maintainer project. Airlock is not on PyPI; the current release candidate installs from a source checkout. The stable 1Password CLI op-items lane uses a current stable CLI, while direct Environments and MCP workflows require tested 1Password beta builds. Supported platforms: Airlock is POSIX only on macOS and Linux. Windows is not supported. Read the prerequisites and supported platforms and project status before installing.

Quickstart

Install the checked-out source, then inspect what your repository needs:

# From the Airlock checkout
uv tool install .

# From the repository Airlock should inspect
cd /path/to/repo
airlock status --repo .
airlock init --repo .

Do not install the unrelated airlock package from PyPI.

status and init do not change the repository or 1Password. They may refresh value-free user caches. Follow the typed action they return, and stop at a human action or an approval marker. Vault writes are gated by 1Password's own approval.

Continue with the tested first-run guide to reach a successful application run. Joining an existing Airlock repository? Use the teammate quickstart.

An authorized application process still receives plaintext, and a malicious or tricked agent with command execution can attempt exfiltration. Airlock is not a sandbox or a vault.

What the first command returns

On a value-free fresh repository, the read-only front door produces this real, generated transcript:

# Generated from a value-free Git fixture by scripts/generate_launch_assets.py.
$ airlock status --repo .
Position: needs-scaffold
Next required action: command
Command: airlock init --repo . --profile dev --op-account AAAA --mcp-client codex --op-command op
Action contract SHA-256: 0b1a2d933285e65fc6783d2fccf2325cd3cea1d158562573f969b879067408b8
Repository changes: none

The committed status transcript is generated and drift-checked with the CLI. It contains a value-free position and one typed next action, never a secret value.

The generated Environment-init transcript shows the alternate program emitted by init.

The security boundary

In normal agent workflows, secret values stay out of prompts, plans, structured Airlock results, request metadata, Git, and public artifacts. Airlock passes names, op:// references, profiles, paths, and typed actions through those surfaces. Output from an authorized application process is outside that claim.

Airlock reduces exposure and authority; it does not make an agent trustworthy. An authorized application process receives plaintext when it runs. A malicious or tricked agent with command execution can try to print or exfiltrate it. Airlock is not a sandbox, and it is not a vault.

Enumerated local commands can inspect or deliver plaintext inside the Airlock process. That handling is invocation-bounded: process exit is the cleanup boundary, no value-bearing session survives between commands, and no memory-zeroization guarantee is made. reveal is a deliberate human-only exception that prints one dev-tier value to an interactive terminal and writes an audit record; agents must not run it.

1Password remains the human and team source of truth. Production and CI should use provider-native identity or provider secret stores where available. See Security for the threat model and private vulnerability-reporting path.

How does an agent connect?

Start with the agent integration guide. It covers Codex, Claude Code, generic MCP clients, and the explicit no-MCP fallback. The Airlock skill tells an agent when to invoke the CLI; the generated CLI reference defines every command and write boundary.

Airlock coordinates setup and emits typed continuations. It does not replace a coding client's permission model or 1Password's approval UI.

What has been tested?

Hosted CI exercises Python 3.9 through 3.13 on Linux, boundary versions on macOS, a network-isolated suite, built wheels and zipapps, secret scanning, and the Cloudflare reference issuer. The packaged-artifact dogfood record records the bounded real-1Password macOS exercise behind the quickstart, including Codex, a generic MCP client, and a no-MCP fallback.

That record does not claim Windows support, every 1Password build, live production, signing, publication, or a PyPI install. See the evaluation guide for supported, possible-with-effort, and unsupported outcomes.

When is Airlock the wrong choice?

• Use a deployment platform's secret store or provider-native identity for a production runtime.
• Keep breakglass access in a separate human-only path.
• Use sandboxing, process isolation, and egress controls to contain hostile code.
• Use raw 1Password tooling when a small, human-owned script already provides the narrow workflow you need.
• Do not use Airlock to normalize broad plaintext dotenv files.

Where do I go next?

• Documentation map: get started, how-to, reference, and concepts.
• Troubleshooting and FAQ: safe remediation and direct boundary answers.
• Project status: pre-1.0 support scope and single-maintainer expectations.
• Migration away: return to raw 1Password workflows without a proprietary export.
• Contributing and the public writing standard: local development and documentation conventions.

Airlock is licensed under the Apache License 2.0 and is not affiliated with or endorsed by 1Password.