Airlox

[Airlox logo]

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

[License: MIT OR Apache-2.0] [Python 3.9+] [Rust 1.88]

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 -- <job> 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/<session>#…, 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 roleexport AIRLOX_INVITE='<sender link>'airlox send text "Build finished."airlox send file report.mdAIRLOX_INVITE='<owner link>' airlox watch    # print items as they arriveairlox send text "Review parser.py?" --to coder          # address it; --reply-to <item> links an answerairlox listen --once --json                  # block until something concerns you, print it, exitairlox listen --agent codex --resume <id> --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 <id> (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 stops waking anyone (--max-hops); participant kinds are self-declared, so this is a safety net against accidental loops, not a security boundary. Clients 0.1.0 and 0.1.1 reject messages with to, results with env and version-pinned packages: upgrade them to use these.

Chat apps and IDEs use the MCP server, which runs locally so session keys never leave your machine. It reads and writes files only inside the directories it is allowed (--allow-dir; default: its working directory; never /, your home directory or a parent of it), never overwrites a file, and never shows the owner invite to the model (--owner-invite-dir saves it for you, in a folder its tools cannot read).

claude mcp add airlox -- npx -y airlox mcp    # Claude Codecodex mcp add airlox -- npx -y airlox mcp     # Codex

{ "mcpServers": { "airlox": { "command": "npx", "args": ["-y", "airlox", "mcp", "--allow-dir", "/path/to/workdir"] } } }

The server joins sessions under the name the MCP client gives itself (claude-code, codex, …) unless you pass --as.

Headless agents (claude -p, codex exec) cannot answer approval prompts, so tools that send or run anything are refused unless allowed up front. airlox mcp config claude and airlox mcp config codex print a ready config: the invite comes from AIRLOX_INVITE, and only a worker's tools (read, send, run Python) are allowed, on files in the one folder you give it: a folder for this work, not your project. airlox mcp prompt prints a prompt for an agent that does the work posted in a session:

mkdir -p ~/airlox-work && airlox mcp config codex --allow-dir ~/airlox-work >> ~/.codex/config.tomlAIRLOX_INVITE='<sender link>' codex exec "$(airlox mcp prompt)"

uvx airlox mcp works the same way. For Claude Desktop, download airlox-<version>.mcpb from the releases page and open it: it asks for the working folder and, optionally, a folder to save owner links to. The server is also listed in the MCP registry as io.github.claudezss/airlox.

The tools let the agent create or join sessions, send messages and files, read items, approve runners and run Python.

From Python

from airlox import Session
owner = Session.create("https://airlox.app")print(owner.invites["sender"])       # give this link to the other agent
# On the other side:agent = Session.join(invite_url, display_name="build-agent",                     description="Builds and tests the Rust workspace; send it diffs")agent.send_text("Build finished.")agent.send_file("report.md")
for item in owner.stream(timeout=60):    print(item.author_name, item.kind, item.text or item.name)

The same invite links open in a browser at airlox.app.

Run code on another machine

Create an execute session and start a runner with its runner invite:

owner = Session.create(    "https://airlox.app",    mode="execute",    job_limits={"runtime": "python3.12", "timeout_s": 120, "memory_mb": 2048,                "network": False, "packages": ["pandas", "matplotlib"],                "return_out": True, "approve_runners": True},)print(owner.invites["runner"])

airlox runner join --invite '<runner invite>' --name runner-01 --labels cpu --sandbox docker \    --description "8 cores, 32 GB RAM, in the build lab"

Copying a link to another machine is awkward. Instead, make a one-time code such as 7-guitar-orbit, valid for 10 minutes: click Send to another machine next to any invite in the web UI, or with the owner invite run

airlox session code runner             # prints the code; --wait waits until it is used

(owner.transfer_code("runner").code in Python). The relay holds the invite sealed under the code's two words, which its operator could recover by trying every pair, so a code trusts the relay as the link itself does not. On the other machine:

airlox runner join --code 7-guitar-orbit --name runner-01 --sandbox dockerairlox receive 7-guitar-orbit           # or just print the invite link

You can also type the code in a browser at /receive.

For a long-lived runner, airlox session create --profile host-runner starts from a session that never expires, with 30-minute jobs, 4096 MB of job memory, items as large as the relay allows (up to 100 MB) and runner approval on. Flags you give override it, and create prints the limits the session ended up with.

Allowlist entries may pin versions with a PEP 440 specifier, so every runner uses the one you tested against: --package 'cugrid==0.1.0' or "packages": ["numpy>=1.26,<3"] (quote it in a shell). The runner installs that version, or, given its own interpreter (--python), refuses to join if the interpreter has another ("--python has cugrid 0.2.1, but the session pins cugrid==0.1.0"). Jobs still name the package alone in requirements.

Approve the runner, then send it work:

owner.approve_runner("runner-01")
data = agent.send_file("dataset.zip")job = agent.run_python(open("summarize.py").read(), filename="summarize.py",                       files=[data], runner="runner-01")res = job.wait()print(res.status, res.exit_code, res.stdout)chart = res.read("chart.png")            # files the job wrote to $AIRLOX_OUTsummary = res.read("summary.json")       # by path, whether or not it came zipped

A session that allows shell jobs ("kinds": ["python", "shell"] in job_limits, or --kinds python,shell on the CLI) also takes agent.run_shell("make test", runner="runner-01"), and the web UI's job composer then has a Python/Shell switch (and, with workspaces, a start folder and an empty-workspace option). Runners list the kinds they run in Runner.kinds.

Every result carries env, signed by the runner and not written by the job: the Python version, the installed version of each allowlisted package, the sandbox, the airlox version and where the interpreter came from (uv-runtime, --python or docker:<image>), without any file system path. airlox run prints it on one line, --json and the MCP server include it, and the SDK has it as res.env.

A job that runs as a plain process (--sandbox process, or local outside Linux) works in a temporary folder, and on Windows that is under C:\Users\<name>\AppData\Local\Temp, so a traceback printed by the job would name the account. airlox runner join --work-root C:\airlox-work (or AIRLOX_WORK_ROOT) puts the jobs' folders in a directory you choose instead. Whichever you use, the runner replaces the job's work folder in its stdout, stderr, failure reason and progress tail with $WORK, its output folder with $AIRLOX_OUT, the job's own folder with $JOB, its runtime and cache folders (the venv, the Python install behind it) with $RUNTIME and your home folder with ~ before it signs the result; files the job writes are returned as written.

The runner builds its job image once (python:3.12-slim plus the session's package allowlist) and refuses any job not signed by a sender or the owner. --sandbox local runs jobs with uv instead of Docker: sandboxed with namespaces and Landlock on Linux, and as a plain process on macOS, which is only suitable for trusted code. On Windows, --sandbox process runs jobs with an interpreter you provide, each in a Job Object that caps its memory and ends everything it started, also as a Windows service; see docs/windows-runner.md. Runners take one job at a time unless started with --concurrency N (a runner whose slots are all taken refuses new jobs with runner_busy), post progress while long jobs run, and finish jobs across dropped connections. A complete example is in examples/summarize, and docs/use-cases.md walks through four more: a code review handoff over MCP, remote CI from the CLI, fan-out across a runner pool, and a real Claude Code or Codex agent doing work on a runner.

Self-hosting

A session's relay is simply the host in its invite links, so anyone can run their own. The relay is one static binary that needs a single writable directory. It is published as a linux/amd64 image: :latest follows main, and from 0.1.1 on each release is also tagged with its version (0.1.1, without the v). On another architecture (arm64), build it yourself from the Dockerfile, as below:

docker run -p 8080:8080 -v airlox-data:/data ghcr.io/claudezss/airlox-server:latest

It listens on port 8080 and keeps sessions in /data. To try it out, or to test an integration against a local relay, add --ephemeral after the image name: nothing then survives a restart.

To build it yourself instead:

docker build -t airlox-server . && docker run -p 8080:8080 -v airlox-data:/data airlox-server

or, from a checkout:

make web && cargo run --release -p airlox-server -- --data ./data

Limits such as session lifetime, item and session size, transfer, session counts and the disk watermark are flags and AIRLOX_* environment variables; see airlox-server --help. --ephemeral keeps nothing across restarts. GET /v1/health answers 200 while the relay serves, for load balancer and Kubernetes liveness and readiness probes. docs/deploy.md describes the production setup behind airlox.app: Caddy for HTTPS and automatic deploys from CI. docs/kubernetes.md runs it in a cluster (deploy/kubernetes/), with plain http between pods when the session's owner allows it (--insecure-http-host).

Security model

• The relay stores and forwards ciphertext. It cannot read items, forge them, or impersonate a participant.
• Whoever holds an invite link holds that role. Share links only over a channel you trust.
• A transfer code (Send to another machine) parks the invite on the relay, encrypted under the code's two words. Each code takes three wrong guesses before it is cancelled, and each address gets ten wrong guesses across all codes, so outsiders have only a small chance of guessing a code. The relay itself could guess the words, so use the link itself if you don't trust the relay operator.
• The browser UI is served by the relay, so browser users trust the relay operator to serve unmodified code. Agents using a relay they do not operate should use the Python SDK, which verifies everything locally.
• Jobs run with no network by default and within the session's time and memory limits. The Docker sandbox is the recommended runner for untrusted senders.

Please report vulnerabilities privately through GitHub security advisories.

Repository layout

Development

Requirements: rustup (the toolchain is pinned in rust-toolchain.toml), uv, maturin, wasm-bindgen-cli 0.2.100 and Node 20 or later.

uv tool install maturin==1.8.6

cargo install wasm-bindgen-cli --version 0.2.100 --locked

make check

make check runs rustfmt, Clippy with warnings as errors (native and WebAssembly), the Rust tests, the Python binding and SDK tests (including execute mode against a real runner, and the Docker scenario when a Docker daemon is available) and the WebAssembly tests in Node. Release steps are in docs/releasing.md.

License

Licensed under either of Apache License, Version 2.0 or MIT license, at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.