Get Started

Steps a person repeats on real machines and accounts, so that a change doesn't break what already works. The pages run the scripts first, then cover what needs a person, such as a Mac, a phone or a real channel.

A script does everything it can: cargo test, the live tests and src/tests/sandbox/run.sh.

# on the branch to check, in the checkout that installs
git fetch && git checkout <branch>
cargo build
# the clouds, in a home of the run's own: a few cents
src/tests/live/run.sh --checkout
# the sandbox with real traffic, in a home of its own: free
src/tests/sandbox/run.sh

Then each page below, top to bottom.

Part	Page	Last passed
Sandbox	The Sandbox	Sep 30 2026 on a Mac. Oct 2 2026 on Linux, in a container, as root and as nobody. An agent's sandbox Oct 5 2026 on Linux, in a container with systemd.
Agents	Agents	Sep 30 2026 on a Mac mini, with OpenAI, Slack and Discord

What a run needs

The accounts cost a few cents a run, and the keys stay outside the checkout.

This checkout's lnk, installed with cargo as Install lnk says. Add plugins with cargo install, never lnk up or lnk plugin add, which download the last release's.
A Mac, as yourself, with your phone. For what needs another computer or an older version, a second macOS user or a second Mac.
A Linux machine of your own, or a box (lnk box start gcp) with this checkout on it, as below.
Accounts: AWS or Google Cloud signed in with aws or gcloud for boxes and buckets, a hosted model's key from Anthropic, OpenAI or OpenRouter, and a channel to text your agent on, which is Telegram, Slack or Discord.
The keys, in one file outside the checkout such as ~/.config/link/qa.env with chmod 600. Each session sources it and gives lnk what it asks for from there.

Run it in lanes

lnk's state belongs to a user, not a checkout. It is ~/.config/lnk, ~/Link, the Keychain and the background services, and two sessions running lnk as one user on one machine share all of it. So a run is split into lanes by machine or by user, and the lanes run side by side:

Lane	Runs as	Runs
Scripts	Your Mac, in homes of their own	The live tests and the sandbox script
Your Mac	You, with your phone	Each page, one after another
Linux	A Linux machine or a box	Each page's Linux checks
The old version	A second macOS user	The latest release first, then this checkout over it

Start the scripts first, because what runs on a box waits on the live tests' boxes passing. Your phone and browser are shared, so have each lane batch what it needs from you, such as texting the bot, scanning a code or clicking Allow, and say when it's waiting.

Only one checkout installs. A lane that finds a bug fixes it in a worktree and merges the fix into the run's branch, and that one checkout builds and installs again for every lane. Two worktrees installing at once leave the Mac with a mix.

This checkout on a box

lnk box start installs the latest release. After each box starts, and after each fix, put this checkout's Linux build over it, as src/tests/live/run.sh --checkout does. The build needs the tools listed in Live Tests.

cargo zigbuild --release --locked --target x86_64-unknown-linux-musl -p link-cli \
  $(for d in src/local/plugins/*/; do printf ' -p %s' "$(sed -n 's/^name = "\(.*\)"$/\1/p' "$d/Cargo.toml" | head -1)"; done)
cd target/x86_64-unknown-linux-musl/release
# every program onto the box, each moved into place
COPYFILE_DISABLE=1 tar -cz ./lnk $(ls lnk-* | grep -v '\.') | lnk box ssh gcp-1 -- 'set -e; d=$HOME/.lnk-qa; rm -rf "$d"; mkdir -p "$d"; tar -xz -C "$d"; mv -f "$d"/* "$HOME/.local/bin/"; rmdir "$d"'
lnk box run gcp-1 -- --version          # this checkout's version

A run

A run is a branch and a pull request into dev. Run each page top to bottom on the machines it names, fix what fails on the same branch, and run that page again. The pull request says what passed on which machines and updates the table above.

A page holds steps to repeat, with what to run and what you see when it works. A change to a feature updates its page in the same pull request, as it does its security.md.