Security

An environment file determines setup, services and the values they receive. This page describes its trust boundaries; Jobs, Sandbox and Boxes describe the corresponding execution boundaries.

What a file can do

Environment files describe commands that run on another machine. Strict file validation and sandbox rules limit the files they can name and the privileges those commands receive.

Relative files

Unknown keys are refused. Named sandbox specifications and inputs must stay inside the environment bundle. File paths resolve from the source folder; field flags resolve from the invocation folder. Absolute paths inside the bundle are rebased to child-relative names before validation. .. and symbolic links in a file or its parent folders are refused. lnk box copy follows no links either, except system-owned links outside home that only root can create, such as /tmp on a Mac.

Sandbox specifications

Named sandbox specifications have the same checks as lnk sandbox run --spec: they cannot write Link's settings, the home folder itself or a dot folder in it. Copied specifications live in Link's settings on the box, inaccessible to sandboxes, so one stage cannot change a later stage's sandbox.

Root stages and services

A stage or service with user = "root" runs through sudo, outside a sandbox. Root stages run only during image builds on a dedicated box removed afterward, never during startup. Root services require their own new box and are refused on an existing box.

Other box users

A run as another box user, created with lnk box user add, uses sudo to enter that user's sandbox and home with the environment's variables. A missing user or a request that also names a sandbox is refused before execution. Computers refuse every run as another user.

Root service resets

lnk env reset runs a root service's reset as root only on the dedicated box made with that environment. The creating computer records that box's cloud ID, tying the reset to a box already running the environment's root service.

Image credentials

Image builder boxes use lnk box create --lnk.login=false. They never sign in to your account, so the commands that build an image hold no account token of yours.

A box or your computer

The machine boundary permits root setup only on boxes. Export validation also limits which environment a computer accepts, independently of whether its image hash matches.

Exported files

The environment transfer interface carries the environment file and named inputs, limited to 1024 text files and 8 MiB. Import stages them privately, refuses absolute paths and .., checks the environment and hash, and rejects extra files before installing any. A computer requires an exact match to its reviewed copy, including start stages, services and every input; the image hash alone is insufficient.

Machine marker

Only a box builds images or runs root stages. lnk reads the machine's kind from /etc/lnk/kind.toml, represented by link_machine::machine::Kind; a file cannot override that boundary.

# /etc/lnk/kind.toml
# Written at the box first boot
kind = "box"
os = "ubuntu-24.04"   # the box spec's OS, which its image is built for
arch = "x86_64"

First boot

lnk box create supplies the marker through cloud-init's write_files at first boot, before user commands. Root owns the file and its folder, with file mode 644. Boxes made from images receive the marker again. An adapter without cloud-init creates no marker, so lnk treats that machine as a computer.

Missing or untrusted markers

No marker, or kind = "computer", means a computer; nothing is written on a personal machine. The marker and every parent folder must be root owned and unwritable by others, except sticky folders such as /tmp. An untrusted marker is refused rather than interpreted. A program or user cannot mark a computer as a box without already having root on that machine.

User namespaces

A user namespace such as unshare -Urm can make a mounted marker appear root owned. lnk refuses it unless /proc/self/uid_map maps every user ID to itself. This is best effort: the namespace can also replace /proc. Even then, root runs use sudo, which gains no machine root in that namespace, so a forged box runs only non-root stages. A sandbox's /etc contains only what its programs need.

Root execution checks

On a box, lnk env image create here permits root image stages and the target runner permits root runs, including services and jobs on their own boxes. On a computer, that runner refuses image builds and any request with root work before execution, and checks again before each root run. Root work uses sudo -n with privileges the box user already has; the computer's sudo is never requested.

Test substitutes

Only debug builds read LNK_SUDO, a substitute for sudo, and LNK_TEST_MACHINE_KIND, a user-owned replacement marker used to test a stand-in box. Release builds ignore both substitutions.

Where values go

Variables are ordinary configuration; secrets require grants bound to a specific file. The two connections have different storage and execution rules so an image cannot retain a granted secret.

Variables

Variables appear as text in the environment file, images, output and records. A name containing a secret-like word (token, key, secret, password or auth) is refused, helping keep credentials out of this ordinary configuration connection.

Your yes

An environment you run acts as you: it's given a secret its file names only once you've said yes, kept in your Safe by the env module for the file's real path, its name and the secret's ID, never in the file (Approvals). A copy, a moved file, a changed name or a secret made again asks again. A run no one is there to answer is refused a secret with no yes, and a job, which runs with no one there, is given none.

Secret recipients

Stages receive the secrets you approved. A sealed value reaches them only as a placeholder, which the proxy fills for its host. Services and image builds receive no secrets, so a built image cannot keep one.

Gaps

Environment validation does not make arbitrary commands trustworthy. These remaining boundaries matter when reviewing an environment file or allowing setup to change files on a machine.

External root services

Root services execute the environment file's commands on its dedicated box. A file you did not write requires --others and a box of its own; review those commands before permitting it to run.

Execution follows workdir and stage paths through links already on the machine. If a stage changes workdir into a link to another folder, subsequent work begins in that destination.