Environments Guide
Use an environment file to check setup, build a reusable image, and run work with the same staged inputs and services. Start by validating a minimal file, then add the stages and services your work needs.
mkdir link-env-examplecd link-env-examplecat > env.toml <<'EOF'
schema = 1
name = "app"
version = 1
EOFlnk env check --spec env.tomlThe environment file
The file declares setup in order: values, stages and services. A stage names its own sandbox, and the services it starts are available to agents and jobs using the same environment.
# env.toml, in the repository it sets up
schema = 1
name = "app"
version = 1
os = "ubuntu-24.04" # left out, any: an image is built for each OS it's asked on
workdir = "app" # where a job, an agent, a service and a start stage begin, from the home folder
# Variables: not secret, written here, given to every run.
[variables]
REDIS_URL = "redis://localhost:6379/0"
# Stages, in order: those saved in the image from the home folder, the rest from the workdir.
# Each runs in the sandbox its spec gives.
[[stage]]
name = "system"
run = "apt-get install -y python3-pip redis-server"
user = "root" # outside any sandbox, as root: only while the image is built
[[stage]]
name = "clone"
run = "git clone https://github.com/me/app app"
sandbox = "clone.toml" # writes ~/app and its .git (write_dot_files), reaches github.com
[[stage]]
name = "deps"
run = "python3 -m pip install --no-cache-dir --target app/.deps -r app/requirements.txt"
sandbox = "deps.toml"
inputs = ["requirements.txt"] # files whose contents count in the image's hash
timeout = "10m" # reaching it fails the build
[[stage]]
name = "pull"
run = "git -C app pull --ff-only"
sandbox = "clone.toml"
when = "start" # runs at every start, never saved in the image
[[service]]
name = "redis"
run = "redis-server --dir /var/lib/redis --port 6379"
sandbox = "redis.toml"
ready = { port = 6379 } # or { run = "redis-cli ping" }; timeout = "60s" by default
reset = "sh app/scripts/reset-db.sh"Every key is on the Environment Spec.
- Paths (
sandbox,inputs) are from the file's folder, written relative, without..and through no link. A sandbox spec's own paths are best written from~/, as the box's home folder: the specs are copied to the box, into Link's settings there. - A stage names its sandbox spec, or
user = "alice"to run as a user of the box in their own sandbox, oruser = "root"to run outside any sandbox as root, which only happens while the image is built, on a box made for that. A stage withoutwhen = "start"is saved in the image. Cloning is a stage: several repositories are several stages. - A service runs in its own sandbox spec, or as root (
user = "root", Docker included) on a box of its own only.readyis a port of the machine's loopback that takes a connection, or a command, run in the service's sandbox, that passes. A service ready on a port serves it on the machine's loopback, so what runs reaches it with that port in its spec's[localhost] ports. - What a job or an agent runs in isn't the file's: a job's stages name their sandboxes, and an agent its own.
- Names of the file, its stages and services are lowercase
letters, digits and dashes. A variable's name is capital letters,
digits and
_, and not one Link sets (LNK_...,PATH,HOME). A variable named like a secret (API_TOKEN) is refused (below). - An unknown key, a spec or input that's missing, or a value that
can't be is refused when the file is read, naming its line, by
every command that reads it. A file of the shape Link read before
(
[box],[run],[repository], a stage'sspec,rootorevery) is refused naming what replaces each key,[repository]with its clone stage.
Parallel stages
A stage can instead contain a named parallel array of command stages.
Its members start together, each in its own sandbox, and all finish
before the next stage. A member cannot be another group. The group's
optional timeout bounds every member; each member may also have its
own timeout. Members use the same when. Their output lines start
with [name]. The first failure received is returned after the other
members finish. Grouping and member order affect the image hash.
The image and its hash
Check the file before creating an image, then build it on the selected cloud account. The hash identifies the setup shared by the boxes made from that image.
lnk env check --spec env.tomllnk env image create aws --spec env.tomllnk env image create aws --spec env.toml --timeout 1hImage inputs
The image's hash is made from what builds the image alone: the file's
name and workdir, the OS (the file's, or the box's when it names
none) and the box's processor, the variables, and each stage saved in
the image, its command, its user, its sandbox spec and its inputs. A
changed lockfile makes a new image; a comment, a service or a
stage run at every start doesn't, and a box made from the image is
given the file as it is now.
Build lifecycle
To build one, a box is made for it (the
least that works, on the file's os), each stage saved in the image
run, the box saved with the hash (lnk box image create --hash), and the
box removed, whatever happened. The cloud bills the box while it runs
and the image for its storage, so lnk env image create asks before making
either. --yes answers yes, and with no terminal and no --yes it
makes nothing and says to add --yes. --timeout ends the
build as failed, its box removed as at any end; left out, only each
stage's own timeout limits it.
Build on an existing box
An image is a box's: your computer is never one. On a box, lnk env image create here --spec env.toml runs the stages saved in the image there,
as on a box made for it, root's included, for the box's OS and
processor, and prints the lnk box image create that saves it, run on the
computer that made the box, which holds its cloud account. On your
computer it's refused before anything runs. What says which a machine
is: Security.
Native cloud jobs
A cloud that builds images and runs jobs itself, with no box of lnk box's, builds a job's image there when the job asks for it: Jobs.
lnk env image create always builds on a box made for it.
Start without a custom image
An environment with no stages saved in an image starts directly from
the cloud OS image when a box is made with it. Its start-stage
inputs and services are copied and started on that VM; no separate
image-builder VM is made. Explicit lnk env image create still builds an image.
Set a machine up without an image
Setup runs image stages without saving an image, on an existing box or on this computer. A computer accepts sandboxed stages and refuses root stages before starting any of them.
lnk env setup --spec env.toml --on web-1lnk env setup here --spec env.tomllnk env setup runs the stages an image would save, in order, each in
its sandbox, and saves no image. On a box each runs as the file says,
root's as root. On your computer a root stage is refused before any
stage runs, since nothing there runs as root
(Security); a file of sandboxed
stages alone sets up a checkout's dependencies, each writing only what
its spec lets it. A
file naming an OS is refused on a box of another, before anything runs.
In a macOS guest
A local VM's guest is set up through its login: a Linux guest's root,
so each step runs as the file says, or a macOS guest's approved ordinary
user, never root. In a macOS guest every stage and service runs as that
user in its sandbox, with the environment's files under its ~/.lnk
and nothing written in /etc. A stage or service as root or as another
named user is refused before any file reaches the guest. The base needs
Xcode's command line tools rather than Rust, since Link's programs come
from the host. A file naming os = "macos" fits any macOS release.
Make a box from it
lnk env create makes a cloud box from the environment, building an image
when no matching hash exists, then starts its services and waits for readiness.
Use a connected cloud account, and pass --box when you need a particular
machine specification.
lnk env create --cloud aws --spec env.tomllnk env create --cloud aws --spec env.toml --box box.toml --name web-1Billed Resources
Creation asks before making a billed box or image. Without a terminal,
--yes is required. Once you agree, nested box and image operations receive
that confirmation so they do not ask again.
Captured Inputs
The box creation workflow
also accepts an environment through --env. It captures the file and
named inputs once, checks the requested OS and processor, reuses or builds
the matching image, and runs start stages and services from that capture.
Start it again
The services outlive the start and come back when the box does. lnk box start runs the when = "start" stages and services again, from
the captured files. Starts and jobs of one image begun at once on one
computer build it once: each waits for the build under way, then starts
from its image. A VM box runs the environment
inside its VM guest instead (VM Boxes).
Reset an environment
Reset a named service using the environment file recorded when this computer
created the box. For a box without that record, supply the file with --spec.
The reset runs through the environment's service boundary on the selected box.
lnk env reset redis --on web-1Variables and secrets
A variable in the environment file is given to its stages, services, and jobs,
and may appear in an image or output. Keep private values as
Secrets,
named under [secrets]. Environment Approvals records
your permission before the environment receives a secret you hold.
Refused secrets
A secret with no yes is refused by a run no one is there to answer,
naming it and the command that approves it, and an image's build is
given none. A variable named like a secret (a word token, key,
secret, password or auth) is refused when the file is read.
Where things live
Link keeps the record on your computer and the environment files and logs on its box. Configuration describes those files and the service names in detail.
On your computer
~/.lnk/safe/envs/boxes/<box>.json records each cloud box made with an environment,
its environment, its complete file and its cloud ID, so later commands
can recover the environment that belongs to the box.
Environment IDs
~/.lnk/safe/envs/ids.toml keeps each environment's ID, env:<id>, by
its file's real path, and every ID minted here, which is never minted
again.
On a box
~/.lnk/safe/envs/envs/<name>/ holds the file and specs, while
~/.lnk/safe/envs/logs/ holds service logs. A job's records and output are
specified by Jobs.
Find a failure's cause
Troubleshooting explains file refusals, missing grants, build deadlines and failed service readiness checks. The command output names the line, stage or service that needs attention.
Command reference
Every flag is in lnk env <command> --help; a job's are
Jobs'. Security has what Link
guarantees and its gaps, and Decisions why it works
this way.