Developer Boxes

Build your checkout and try it on a cloud box with one command. The helper manages a personal signing key, local release files and a separate dev CLI, leaving your installed lnk unchanged.

# From the public workspace with your changes committed
./scripts/dev-box.sh gcp

Before you begin

Use macOS or Linux on ARM64 or x86-64, with Bash 3.2 or later, Rust installed through rustup, Git, jq, curl, shasum, tar and OpenSSH 8.1 or later. Configure your cloud account in lnk first, with permission to create and remove machines. A box costs money while running, and its disk costs money until removed. The helper keeps the normal cost confirmation before creation.

Set up a Mac

The built-in macOS Bash is supported. Install Xcode command-line tools and Rust through rustup if they are missing. With Homebrew installed, add the cross-compilation tools below. The repository's toolchain file selects the Rust version automatically.

brew install jq zig
cargo install cargo-zigbuild --locked

Set up Linux

Install Git, a C compiler, jq, curl, Perl's shasum, OpenSSH and tar through your distribution, Rust through rustup, and Zig on your PATH. Add the Cargo cross-compiler below. The helper checks for required programs before building.

cargo install cargo-zigbuild --locked

Choose a commit

Commit or stash changes before running the helper. It builds exactly HEAD from a clean checkout, including when you are on a feature branch. A commit is local and need not be pushed. Generated files ignored by Git do not make the checkout dirty.

Create a box

Run the helper from link-public/, using your configured account's name. It builds a signed dev release for your host and Linux x86-64, installs its CLI and plugins into a separate cache, and creates <account>-dev. The first build compiles the plugins supported on both your host and the box and can take a while. Build progress remains visible.

./scripts/dev-box.sh gcp

Choose the machine

Put ordinary creation flags after --. For example, choose the GCP machine type below. The helper manages the release version and rejects --spec so a spec cannot silently choose a different release.

./scripts/dev-box.sh gcp -- --size e2-small

Choose ARM64

Use --arch arm64 before -- to build for an ARM64 box instead. Pass the same option when updating it. The helper requests that processor from the cloud and builds only your host and the selected box architecture.

./scripts/dev-box.sh gcp --arch arm64

Name the box

Use --name before -- to choose a name other than <account>-dev. Keep that name when updating the box. Creation never silently reuses or replaces an existing box.

./scripts/dev-box.sh gcp --name gcp-1 -- --size e2-small

Update after a change

Commit the next change, then run --update. The helper builds or reuses that commit's release, copies it to the existing box over SSH, and runs a verified upgrade of its CLI and installed plugins. It uses the same personal signing key as creation. Updates preserve the machine and its files, and do not create a replacement if it is missing.

./scripts/dev-box.sh gcp --update

Update a named box

Pass the same --name used at creation. Creation flags do not apply to updates. This command updates Link's programs, rather than syncing your project's working files or restarting your applications.

./scripts/dev-box.sh gcp --name gcp-1 --update

Connect and clean up

The dev CLI shares your normal Link account and box records. Use your installed lnk to connect to the name printed at completion. A retained development box stays available until you remove it.

lnk box ssh gcp-dev

Remove the box

Remove the machine and its disk when finished to stop their charges. The helper never removes an existing development box automatically, including when a later update fails.

lnk box delete gcp-dev

Local state and trust

The helper stores its signing key at ~/.lnk/dev/signing-secret, releases and a separate CLI beneath ~/.lnk/dev/, and a Cargo build cache shared across commits of this checkout. Completed releases are reused for the same checkout, commit, signing key, host and box processor. No bucket, public upload, global environment change or replacement of your installed lnk is needed.

Keep your signing key

The key stays on your computer and is never copied to a box. Keep it between builds because each box trusts the key used to create it. A box created with another key refuses the upgrade. A regular release CLI also refuses dev releases. See A dev build for the signing contract and lower-level release tools.

Recover from failures

A failed build or installation leaves no completed-cache marker, so the next run tries again. An interrupted update can be retried with the same command. A hard kill can leave an empty lock directory, whose exact path the helper prints on the next run. Remove that directory only after confirming the earlier helper has stopped. For missing prerequisites, follow Before you begin.