Bundle
lnk bundle builds any set of Local Link's programs from source into one
signed folder that every installer already reads. Every bundle has one
stage, development, staging or production, and the stage says what the
bundle's lnk trusts. Use lnk bundle to make Local Link's release, a
staging build, a dev build for your own boxes, a production bundle of your
own, or a bundle of your own programs beside Local Link's. The
Bundle Spec lists the fields, as a file or
as flags.
lnk bundle listBefore You Begin
Run lnk bundle from a checkout of Local Link's source with every tracked
change committed or stashed. A file Git doesn't track, such as a log, is never
built, so it doesn't stop a build. You also need
Rust installed through rustup, Git, tar, curl and OpenSSH 8.1 or
later, and zstd for an outside program from a Debian package. Building for another machine's target also needs Zig and cargo zigbuild, as the dev boxes guide
sets up.
Prebuilt Bundles
The module comes with the bundles Local Link's own work uses. Each is a spec
file you create by name, and lnk bundle list lists them.
devbox
The devbox bundle holds this computer's lnk, the modules that make a
box and reach its cloud, and the secret and sandbox modules every box
installs beside lnk. It also holds what an agent moved there runs: agent,
its harness, model, which serves its model calls, and mcp with the
man it needs. It builds for this computer and for the box, and your own
dev signer signs it. The programs for this computer land in the bundle's
bin folder, ready to make a dev box.
link
The link bundle is Local Link's public release. It holds lnk and every
module the release ships, for every target. It is a production build
compiled to trust Local Link's signer, link, and signed by that signer.
CI builds it one target per runner and seals the parts, and
the release workflow publishes it.
prodbox
The prodbox bundle makes a production box of your own. It holds lnk and
every module Local Link's release ships, for this computer and Linux boxes,
and your own prod signer signs it. Its lnk trusts that signer alone, so
the box installs only what you signed and never Local Link's own releases.
lnk bundle create prodboxlnk box create aws|gcp --name prod-1 --bundle prodboxstaging
The staging bundle holds lnk and every module, for Linux on x86_64 and
arm64, where boxes run them. The staging signer signs it, so you can try a
commit on boxes before it ships. Copy it to a bucket, and it installs as a
release does.
Signers
A bundle is signed by a signer you keep by name in the Safe, and the
bundle's stage says which signers its lnk trusts. Signers
shows how to make one, where each is kept, and which signers are Local
Link's own.
Create a Bundle
lnk bundle create builds the programs for each target. It builds each
workspace's programs in one Cargo build, so the crates they share compile
once. Then it packs each program in its own archive, and seals and signs
the archives. Name the workspaces to find programs in, the programs, and
the targets. Leave them out for this checkout, lnk and every module, and
this machine.
lnk bundle create --target x86_64-unknown-linux-musl --signer devChoose the Programs
--program takes a program's file name, such as lnk-measure, and
repeats for more. --source adds another workspace to find programs
in. A program two workspaces build is refused, since a bundle holds one
of each.
Choose the Targets
--target takes one of Local Link's release targets, each an operating
system on a processor architecture, and repeats for more:
x86_64-unknown-linux-musl and aarch64-unknown-linux-musl for Linux on
x86_64 and arm64, and x86_64-apple-darwin and aarch64-apple-darwin for
macOS on each. host stands for this computer's own. Any other target is
refused, from a spec file or a flag alike, since no installer would find
its archives. Each program is built for each target, so every target you
add makes the build take about as long again.
Choose Its Stage
--build names the bundle's stage, dev, staging or prod. The stage
says which signers the bundled lnk trusts and how its version reads. A
staging or dev build is built in a worktree of your commit with its version
set, so your checkout is left as it is. The version carries the commit's
build ID. The build ID is the commit's time in UTC to the minute, which
orders builds, then g and the first twelve characters of the commit's
hash, which names the commit. So every machine that builds one commit gives
it one version.
Find the Build Worktree
The worktree is kept, one per checkout, at bundle/source in the first
source's Cargo target folder, such as link-public/target/bundle/source,
and the build's output stays in that target folder too. Each build
moves the worktree to its commit with git checkout --detach --force
and removes every file the commit doesn't track, so it still builds
the commit and never your uncommitted changes.
What a Build Reuses
A file the two commits share keeps its time, so Cargo reuses what it
built from that file when nothing else changed. Every member's version
still changes with each commit, so a build of a new commit compiles the
workspaces' own crates again, and reuses only the third-party crates. A
second build using the same worktree is refused while the first holds
bundle/source.lock.
Build the dev Stage
The bundled lnk trusts the bundle's own signer and Local Link's, at a
version such as 0.14.0-dev.202611090720.g1a2b3c4d5e6f. A signer of
your own signs it, never Link's nor the staging signer, so no released
or staging lnk installs it.
Build the staging Stage
The bundled lnk trusts Local Link's signer and the staging signer, at
a version such as 0.14.0-staging.202611090720.g1a2b3c4d5e6f. Only the staging
signer signs it. That signer is the one the source's
scripts/release/staging-signers names, which the bundled lnk is
compiled to trust. A source of your own may
name a signer of yours there, kept under any name, and its staging
builds then install each other's, and Link's, without Link's signers'
secrets.
Build the prod Stage
The bundled lnk trusts exactly the signer it's compiled with, the
bundle's own, and the bundle has the workspace's version, such as
0.14.0. Local Link's release is the production build signed by Local
Link's signer. A production bundle of your own, signed by a signer of
yours, makes boxes that install nothing else. The staging signer never
signs a production bundle.
Sign the Bundle
--signer names who signs the bundle: link, staging, or a signer of
your own by name or by an allowed-signers file. --signing-secret names the
signer's secret file. It is a runtime flag and never a field of a spec.
The secret is read only once every program is built, and the signature is
checked against the signer before the command ends. A wrong secret fails
here, not on the machines that install the bundle.
Unsigned Builds
Dev and production builds require a signer because their programs embed its
trust, including unsigned parts built without Link's signing secret. A staging
part may omit a signer or use --signer none for later sealing with
--from.
Add Outside Programs
--outside names a TOML file declaring programs Local Link doesn't build,
each with its download for every target and the SHA-256 sum it must
have. take names the file to take from an archive.
# outside.toml
[[program]]
name = "caddy"
version = "2.10.2"
[program.targets.x86_64-unknown-linux-musl]
url = "https://github.com/caddyserver/caddy/releases/download/v2.10.2/caddy_2.10.2_linux_amd64.tar.gz"
sha256 = "5c218bc34c9197369263da7e9317a83acdbd80ef45d94dca5eff76e727c67cdd"
take = "caddy"Write a Spec
Every field flag is a field of one spec file, so a bundle you make
often is one file and one command, --spec FILE. A field flag replaces the
field it names, and a file's relative paths start from the file's folder. lnk bundle spec show prints the spec a file, a built-in
bundle or flags make, without building anything.
# bundle.toml
schema = 1
source = ["."]
program = ["lnk", "lnk-box"]
target = ["aarch64-apple-darwin", "x86_64-unknown-linux-musl"]
build = "dev"
signer = "dev"lnk bundle create --spec bundle.tomllnk bundle spec show devbox --target hostSeal Parts Built Elsewhere
A build for several targets can run on several machines, and each machine
makes an unsigned part. One machine that holds the signer's secret seals
the parts with --from.
lnk bundle create --target aarch64-apple-darwin --build prod --signer link --out part-maclnk bundle create --from part-mac --from part-linux --signer link --signing-secret link-secret --out distMake a Dev Box
A dev box runs your checkout's commit. The devbox bundle builds the commit
for this computer and the box. lnk box create --bundle devbox
then makes the box from the newest devbox bundle, through the bundle's own
lnk, which trusts your dev signer.
lnk bundle create devboxlnk box create aws|gcp --name gcp-1 --bundle devboxConnect your cloud account first, as Cloud Accounts describes. To try a later commit, build its bundle again and make a new box from the bundle the same way.
Build in CI
The repository's bundle workflow builds any bundle from the branch you
start it on. Each target builds unsigned on its own runner, then one job
seals the parts with --from. Only that job receives the signer's secret,
through the bundle-<signer> GitHub environment. Set the environment's
required reviewers and branch restrictions in GitHub's environment settings.
gh workflow run bundle.yml --ref my-branch -f bundle=staging -f signer=staginggh run download --name bundle --dir bundleEach signer's environment supplies SIGNING_SECRET. Local Link's is bundle-link.
The workflow selects that environment, while GitHub's configured protections
determine which branches may use it and whether review is required. The release workflow calls the same workflow for
the link bundle, then publishes what it sealed. file names one more file from the
repository to seal with the bundle, as --file does.
Check a Bundle
lnk bundle show lists each program with its target and the target's
architecture, x86_64 or arm64, so you see which machines the bundle
installs on. --json gives the same rows to another program. When
SHA256SUMS is present, show checks the listed files and rejects extra
files. It checks an existing signature against --signer, or classifies it
against Local Link's signer when you omit --signer.
lnk bundle show devbox --signer devUnsigned Parts
You can inspect a part without sums or a signature when you omit
--signer, and the result says those checks were not supplied. An explicit
--signer refuses a bundle with no signature. A successful unsigned
inspection does not show that the part is a signed release. Only a sealed
bundle carries the signed checksums its installer requires, so keep the
reported signature state with the inspection result.
Install a Bundle
A bundle is a folder in the published release layout,
download/v<version>/ and latest/download/, holding each program's
archive, install.sh, VERSION, COMMIT, SHA256SUMS and its
signature. Every installer reads it as it is, from a folder here or
after a plain copy to a bucket, through LNK_RELEASES_URL
(where releases are read from).
An installed lnk installs only what a signer it trusts signed. The
bundle's own programs, in its bin/, install from the bundle itself, so
a box they make gets the bundle's build.
Where Bundles Are Kept
A bundle goes to ~/.lnk/data/bundles/<name>/<version>/ unless --out
names another folder. The name is the built-in bundle's or the spec file's.
lnk bundle show devbox finds the newest of a name, and a version finds
that one.