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-example
cd link-env-example
cat > env.toml <<'EOF'
schema = 1
name = "app"
version = 1
EOF
lnk env check --spec env.toml

The 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, or user = "root" to run outside any sandbox as root, which only happens while the image is built, on a box made for that. A stage without when = "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. ready is 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's spec, root or every) 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.toml
lnk env image create aws --spec env.toml
lnk env image create aws --spec env.toml --timeout 1h

Image 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-1
lnk env setup here --spec env.toml

lnk 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.toml
lnk env create --cloud aws --spec env.toml --box box.toml --name web-1

Billed 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-1

Variables 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.