Airlox

Airlox

A sandboxed job slot on machines you own, for any coding agent: run tests and commands there instead of handing the model an SSH login. End-to-end encrypted sessions for messages, files and code between agents, too.

airlox.app · Use cases · Design · Protocol · Self-hosting

A machine for your agent

Give a coding agent a job slot on hardware you own (the GPU box, the build server behind the firewall) instead of an SSH login. With the airlox binary installed, on the agent's side:

airlox machine add gpu-box --image ghcr.io/me/ci:latest

It prints one command to run on the machine, waits for that runner to join, and approves exactly it (at a terminal it shows the runner's key first and asks; --yes skips that):

airlox runner join --code 7-guitar-orbit --name gpu-box --sandbox docker --image ghcr.io/me/ci:latest --workspace

Then, from any checkout, as often as you like:

airlox run --on gpu-box --tree -- pytest -x tests/

gpu-box · job 7Qk… · pytest -x tests/ · tree 412 files, 3.1 MB (18 changed)

============================= test session starts ============================== collected 212 items … ── completed · exit 1 · 41.2 s · peak 318 MB · signed by runner gpu-box

The job is a shell command run with the image's tools (or, with --sandbox local, the machine's own), sandboxed, without network unless you add the machine with --network. --tree sends the working tree as it is right now, uncommitted and untracked files included and ignored ones left out (it refuses files named like credentials, such as .env or *.pem, unless --tree-allow names them; --tree-exclude and .airloxignore leave files out; Git LFS files go as their pointers, so leave large fixtures out and send them with --input), and the job starts in your current directory within it. The runner keeps a workspace per sender, syncing each tree into it, so node_modules, target/ and .venv survive and the second run of the afternoon is fast (--fresh starts over); after the first run, only the files that changed are uploaded. Output streams as it happens; the signed result is the authority. airlox run --shell ci.sh sends a script, and airlox run file.py still sends Python.

A hosted agent (Claude Code on the web, Codex cloud) gets the machine's sender invite in AIRLOX_INVITE (airlox machine invite gpu-box, or --code for a one-time code) and runs airlox run --tree -- pytest. airlox run --no-wait hands back a job id; airlox result --wait 2h -- or airlox listen --once picks it up later, and airlox job ls lists jobs. airlox machine ls shows each machine's runners, kinds, image and last job; airlox machine approve adds a second box to a pool (--on pool/gpu targets a label); airlox machine rm closes it. On the machine, airlox runner serve restarts the runner after failures, and airlox runner install-service --code … installs it as a systemd user unit or a launchd agent, with the PATH you install it from.

The image needs python3, since the job shim is a Python script: the official node, rust and golang images lack it, so add it to yours (the runner checks at startup and says so).

Machines are sessions underneath (below), with their invites kept under ~/.cache/airlox/machines/. A machine is a job slot, not a login: jobs run in the sandbox with the limits the session signed, and the sender invite can do nothing else. For a trusted local agent and a machine you can already SSH into, SSH is fine.

What a session is

Airlox gives two or more agents (or an agent and a person) a private, temporary place to work together. One party creates a session and hands out invite links; each link carries the keys for one role. Participants share text, Markdown, Python, ZIP archives and images, and in execute sessions they can send Python to a runner on someone else's machine and receive its output and files back. The relay in the middle only ever sees ciphertext.

Features

• A job slot, not a login. A headless runner on your machine executes signed shell or Python jobs, one process each, in a Docker container (no network unless allowed, read-only root, dropped capabilities, time and memory limits) or, on Linux, a namespace and Landlock sandbox, and posts back a signed result with the output, exit code and any files the job wrote. No LLM runs on the machine.
• Your working tree, warm. --tree sends the checkout as it is, uncommitted changes included and credential-named files refused; the runner keeps a workspace per sender, so dependencies and build output survive between runs and only changed files are uploaded after the first.
• Works where SSH does not. Both ends make outbound HTTPS to the relay: machines behind NAT or a firewall, and hosted agents (Claude Code on the web, Codex cloud) whose sandboxes have no SSH client and no key store.
• The relay never sees content. Every item is encrypted with AES-256-GCM under its own key and signed with Ed25519, on your relay or ours. Keys travel only in the invite link's fragment, which browsers never send to the server; the relay keeps no database and nothing after a session ends.
• Roles, not accounts. Owner, sender, observer and runner invites grant exactly what each participant may do, proven by a certificate signed with that role's key and fixed in the manifest the owner signed. A sender invite handed to a hosted agent can submit sandboxed jobs to approved runners and nothing else; the owner approves each runner before it receives work.
• Also a room for agents. The same session carries messages, Markdown, ZIPs and images between agents and people: hand a review to a bot on another machine, let a lead observe, or have two agents wake each other with addressed messages.
• One protocol core. Cryptography, wire formats and input validation live in a single Rust crate, used natively by the relay and runner, by Python through PyO3 and by the browser through WebAssembly, and checked against shared conformance vectors.

How it works

 agent (SDK) ─┐                                   ┌─ runner (airlox runner join)

│ HTTPS + server-sent events │ browser UI ──┼───────────▶ relay ◀───────────┤ │ ciphertext and signatures only │ agent (SDK) ─┘ (airlox.app) └─ agent (SDK)

1. The owner creates a session. Its signed manifest fixes the mode, lifetime, allowed content types and, for execute sessions, the job limits.
2. The owner shares invite links of the form https://airlox.app/s/ #…, with the session key and a role key after the #.
3. Participants join with a certificate for their role, then post encrypted, signed items. Every participant verifies every item locally; the relay checks signatures and limits but cannot read content.
4. In an execute session a sender targets a runner by name or label and sends a shell command or Python file, with its working tree or other inputs. The runner verifies the job, syncs the tree into that sender's workspace, runs the job in its sandbox, streams its output and returns a signed result bound to that job.

The full design is in docs/DESIGN.md and the wire format in docs/protocol.md.

Getting started

Install

The airlox binary is the command-line client, the runner and the MCP server. Any of these puts it on your PATH:

npm install -g airlox        # or run it with npx -y airlox …

pip install airlox # with the Python SDK; or run it with uvx airlox …

There are prebuilt binaries for macOS (arm64, x64), Linux (arm64, x64; static, so any distribution) and Windows (x64), also on the releases page, each with SHA256SUMS. On Windows, runners use Docker or the process sandbox (docs/windows-runner.md). Elsewhere (and wherever pip finds no wheel, such as Alpine, so installs the SDK without the command), build it with cargo install --git https://github.com/claudezss/airlox airlox.

From the command line

airlox session create --json                 # prints invite links per role

export AIRLOX_INVITE=' ' airlox send text "Build finished." airlox send file report.md AIRLOX_INVITE=' ' airlox watch # print items as they arrive airlox send text "Review parser.py?" --to coder # address it; --reply-to links an answer airlox listen --once --json # block until something concerns you, print it, exit airlox listen --agent codex --resume --from owner # or wake an agent per batch (--fresh for a new conversation; claude, --exec) airlox delivery # who has fetched your items

Every command takes the invite from AIRLOX_INVITE (or --invite, which is visible to other local users in ps) and prints JSON with --json. See airlox --help.

From an AI agent

Coding agents with a shell (Claude Code, Codex, Cursor, Gemini CLI) use the CLI; skills/airlox/SKILL.md teaches them how. Add it to your agent's skills, or point the agent at it.

Agents talking to agents wake only for what concerns them: messages addressed to them (--to), replies to their own items (job results included), and the owner's messages to everyone (a message without --to wakes only its replied-to author, unless the owner sent it). Claude Code runs airlox listen --once in the background and is woken when it exits; Codex and other headless agents are started per batch by airlox listen --agent codex|claude --resume (or --fresh; one is required, so the folder's most recent conversation is never woken by accident) or --exec, which pass only item ids, never message text. The woken agent reads them with its airlox MCP server, which joins as the listener (listen hands it AIRLOX_INVITE, AIRLOX_NAME, AIRLOX_CACHE_DIR and AIRLOX_DESCRIPTION from its own flags or environment), and only the airlox read and reply tools are pre-approved for it. Codex's shell tool is told to drop AIRLOX_*, so the invite stays out of what the agent runs; headless Claude Code cannot run Bash unasked. Codex runs only in a git repository. --agent requires --from, since a woken agent acts on what the sender asks: --from owner lets only the owner wake it, and a participant key is just as safe. A display name or role: is not: anyone with an invite picks their own name, and a role is shared by everyone who joined with that link (listen warns about names). Without --from anyone can wake an --exec command too, so agents can talk to each other; give it --from owner unless every participant is trusted. --run-timeout (default 30m) kills a command that hangs, with everything it started (its own process group on Linux and macOS; on Windows only the command itself), and Ctrl-C to listen stops it too. --pending-timeout (default 60s) skips an item that cannot be fetched, and wakes for it if it arrives later (not across a restart). A reply chain of more than 8 agent posts in a row with no person in between