The .relay archive: export, import & portability
Package a whole project — repos, lanes, recipes, brand, and secrets — into one portable file you can open on any computer by double-clicking, on either macOS or Windows.
Last updated 2026-07-16
A .relay archive is your whole project in one portable file: repos, lanes, recipes, brand, and secrets. It's how you back up a project, move it to another computer, or hand it to a teammate. Double-click one and it opens in AppRelay.
.relay — or opening one — asks you to upgrade first. This article describes the format either way, so you know what you'd be getting.What's inside
The shape differs slightly by platform, and deliberately so: on macOS a .relay is a package — a folder that Finder presents as a single file — while on Windows it's a single file. The contents are identical, which is what lets one move between the two:
| Item | What it holds |
|---|---|
format | A fast version probe for the archive format |
manifest.json | The project value tree — projects, lanes, recipes, brand (pretty-printed, sorted keys) |
assets/ | Per-project icons referenced by the manifest |
secrets.enc | The encrypted secrets blob (AES-GCM ciphertext) |
secrets.meta.json | Key-derivation metadata: KDF, iterations, salt, nonce, version |
history/ | Optional test pass/fail history and settings snapshots |
secrets.enc. See Secrets & encryption.Exporting
- Choose export for the project you want to package.
- Set a passphrase. This encrypts the secrets inside the archive. Choose something strong and memorable — it can't be recovered.
- Save the
.relayfile wherever you like — a shared drive, a repo, a teammate's machine.
The archive is written atomically, so an interrupted export won't leave a half-written file.
Importing
- Open the archive — double-click it, or choose Import a .relay on the empty-state screen.
- Enter the passphrase. A wrong passphrase is cleanly rejected (see below).
- Point at the repo root. Because the archive holds only relative paths, AppRelay asks where the repositories live on this machine. See the repo root.
- Merge or add. The imported project joins your workspace.
Portability by design
Three properties make a .relay safe to move around:
- Only relative paths ship. Nothing in the archive assumes your username or folder layout, so it opens cleanly on any machine.
- It crosses platforms. A project exported on a Mac imports on Windows and vice-versa — same archive, same contents. Only the repo root, which is per-machine anyway, needs re-pointing.
- Secrets are encrypted at rest. The values never appear in the manifest and are unreadable without the passphrase.
Versioning
The archive carries an integer format version in both the format file and the manifest. AppRelay migrates older archives forward step by step, absorbs minor additive changes through defaults, and refuses to open an archive newer than it understands (so a downgrade can't corrupt your data).
.relay like a credential-bearing file: it contains encrypted secrets, but its safety still depends on your passphrase. Share the file and the passphrase over separate channels, and store backups somewhere you trust.