Metadata-Version: 2.4
Name: airlock-cli
Version: 0.1.0
Summary: Airlock coordinates 1Password-backed secret workflows for coding agents while keeping secret values out of the normal control path.
Author: Airlock Maintainers
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/rossbrg/airlock
Project-URL: Repository, https://github.com/rossbrg/airlock
Project-URL: Issues, https://github.com/rossbrg/airlock/issues
Project-URL: Security, https://github.com/rossbrg/airlock/security/policy
Project-URL: Documentation, https://github.com/rossbrg/airlock/tree/main/docs
Project-URL: Changelog, https://github.com/rossbrg/airlock/blob/main/CHANGELOG.md
Project-URL: Contributing, https://github.com/rossbrg/airlock/blob/main/CONTRIBUTING.md
Keywords: 1password,coding-agents,secrets-management
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.10; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=7; extra == "dev"
Requires-Dist: pytest-randomly>=3.15; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.6; extra == "dev"
Requires-Dist: pyyaml>=6.0.2; extra == "dev"
Requires-Dist: ruff>=0.15.20; extra == "dev"
Dynamic: license-file

# Airlock

![Airlock Registry wordmark](docs/assets/airlock/airlock-readme-hero.png)

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](docs/handbook.md#prerequisites-and-supported-platforms)
> and [project status](docs/reference/project-status.md) before installing.

## Quickstart

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

```sh
# 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](docs/quickstart.md) to reach a
successful application run. Joining an existing Airlock repository? Use the
[teammate quickstart](docs/teammate-quickstart.md).

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:

```text
# 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](docs/assets/airlock/transcripts/readme-cold-start.txt)
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](docs/assets/airlock/transcripts/quickstart-cold-start.txt)
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](SECURITY.md) for the threat model and private vulnerability-reporting
path.

## How does an agent connect?

Start with the [agent integration guide](docs/reference/agent-integration.md).
It covers Codex, Claude Code, generic MCP clients, and the explicit no-MCP
fallback. The [Airlock skill](skills/airlock/SKILL.md) tells an agent when to
invoke the CLI; the [generated CLI reference](docs/reference/cli.md) 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](docs/reference/packaged-artifact-dogfood-2026-07-11.md)
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](docs/reference/evaluation.md) 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](docs/README.md): get started, how-to, reference, and
  concepts.
- [Troubleshooting](docs/reference/troubleshooting.md) and
  [FAQ](docs/reference/faq.md): safe remediation and direct boundary answers.
- [Project status](docs/reference/project-status.md): pre-1.0 support scope and
  single-maintainer expectations.
- [Migration away](docs/reference/migration-away.md): return to raw 1Password
  workflows without a proprietary export.
- [Contributing](CONTRIBUTING.md) and the
  [public writing standard](CONTRIBUTING.md#public-writing-standard): local
  development and documentation conventions.

Airlock is licensed under the [Apache License 2.0](LICENSE) and is not affiliated
with or endorsed by 1Password.
