Environment Files
An environment file says what every machine made from it has before work starts. This page explains how its parts fit together; each field is in the Env Spec reference.
Order and Reading
The file's order is its name and version, os and workdir, then the values every run is given, then the stages that set a machine up, then the services it runs.
Validation
Every command that reads an environment takes its file as --spec <file>, with any field as a flag that is its key path laid over it, such
as --variables.REGION eu-west-2; a stage or service is given whole, as
an inline table. A file is at most 64 KB; unknown keys, empty tables and
invalid values are refused with the source line named.
Secrets
The file names secrets; their values and your yes to giving each are this machine's.
Give a secret
Run lnk secret create NPM_TOKEN, then lnk env approval add NPM_TOKEN --spec env.toml to say yes to giving it to that exact file, named
app. Your yes is for the file's path, its name and the secret's ID,
so a copy or a move asks again:
Approvals.
When grants are read
A missing grant is refused before running the file, naming the secret.
lnk env check reads files naming secrets without requiring grants.
Stages and jobs receive granted values; services receive variables
alone. Image builds receive no secrets because images keep what their
stages write.
Machines, users and runs
An environment defines setup shared by agents, jobs and interactive work. Machines, users and runs have separate owners, so the same setup can be carried without changing who owns the machine or starts work.
Machine
A machine is your computer, yours alone and never an image, or a box
made from an image or none and saved as one. here names whichever
machine runs lnk. The box module writes /etc/lnk/kind.toml as root
on a box; without it the machine is a computer.
User
A user belongs to the machine: you on your computer, a box's own user
such as ubuntu, root, or another user of the box. Each run names who
it runs as within that machine's permissions.
Environment
An environment is the values, stages and services every box made from it receives, and the image those stages build. This file and the env module own that setup; the box module owns the machine itself.
Run
A run is a command, as a user, in a sandbox, on a machine. Its caller
owns when it starts and ends. A stage and a job's stage share one type;
an agent is a run that stays up at workdir, with its own sandbox
file, the environment's values and its services.
Kinds of run
Runs differ in when they start, what ends them and which user they may use. Each kind retains the same machine, user and sandbox boundary.
- Stage: starts while an image is built or at each start, and ends by itself. It runs as the machine's user, or as
rootduring an image build. - Service: starts at each start and runs until stopped;
readyreports readiness. It uses the machine's user, orrooton a box of its own. - Job stage: starts with its job and ends by itself or at a stage or job timeout. It uses the machine's user, or
rooton a box of its own. - Agent: starts when asked and runs until stopped, as the machine's user, within its own sandbox.
- SSH session: starts when a person connects and ends when they leave, as a user of the box in that user's sandbox.
Where setup runs
Only a box takes an environment whole: its image is built on a box made for it. Your computer runs start stages, services and jobs, but never build stages or an image build. Current limitations are listed under Not built yet.
Parallel stages
A stage is one command, or a named group of commands:
schema = 1
name = "example"
version = 1
[[stage]]
name = "checks"
timeout = "10m"
[[stage.parallel]]
name = "lint"
run = "./lint.sh"
sandbox = "lint.toml"
[[stage.parallel]]
name = "test"
run = "./test.sh"
sandbox = "test.toml"Members start together, each in its own sandbox. Output lines start
with the member's name. A failing member lets its peers finish, then
ends the build or job with the first failing member's code; subsequent
stages do not run. A group timeout applies to every still-running
member, within the whole run's timeout. A member cannot be a group,
and a stage cannot name both run and parallel. Groups are nonempty;
the group and member names are unique across the file. An environment
group's members have the same when; its image hash includes the
grouping, member order and group timeout.
Image
An image is a box's alone, saved by lnk env image create. Its hash is made
from what builds it, and nothing else:
- the file's
nameandworkdir, itsos(or, left out, the OS of the box it's built on), and that box's processor; - the variables;
- each stage saved in the image: its
run, itsuser, its sandbox spec's contents and itsinputs' contents.
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 cleanup
The box an image is built on is removed once the image is saved or the
build fails. Should lnk never get to it, its cloud ends and deletes
it at its deadline: the build's --timeout and a quarter hour, or four
hours without one. The timer that ends a box on AWS is left out of the
image, so a box made from it never ends at that deadline.
Commands that read it
The same file is read strictly by validation, image, setup and startup
commands. A Job Spec names
its environment with env.
Check and print
lnk env check --spec env.toml reads the file and its named files and
prints the image hash. lnk env spec show --spec env.toml prints the file
with defaults. Serialization reads the file or this computer's record,
never a box's writable copy; paths remain relative to the folder whose
specs and inputs travel together.
Build and start
lnk env image create aws --spec env.toml builds on a dedicated box.
lnk env image create here --spec env.toml builds only on a box, for the
computer that made it to save. lnk box create aws --env env.toml --spec box.toml
makes a box from the image, building first when necessary.
Set up and reset
lnk env setup --spec env.toml --on app-1 runs image stages without
saving an image, refusing root on a computer before anything runs.
lnk env reset redis --on app-1 restores a service, and
service port forwarding opens its port as a
tunnel.
An environment carried to another machine
The environment preparation interface captures declared text inputs and installs them on the target before work starts. Captured Work Directories defines export, validation, preparation, and the target-local paths returned to a caller.
What isn't in it
Other contracts own the machine, work to run and access policy. The environment file links to those contracts instead of redefining their settings.
- The machine's size and cloud: a Box Spec's, named by
lnk box create --envor a job'sbox. - What a job runs: a Job Spec's stages.
- Who comes to a box: never the environment's, which says what a machine has, not who comes.
- An agent's sandbox: its own file
(
~/Link/Safe/Agents/<agent>/sandbox.toml,lnk agent start --sandbox), never made from a stage's. - Secrets: granted to an environment's file, and given to its stages and jobs, never its services or images.
Not built yet
The file is read whole, with two current limits. No command prints the
spec a box was made from. An image-builder box is the least machine
that works on the file's OS, so lnk env image create builds for that OS and
x86_64; only lnk box create --env and a job's box select their
box's size and processor.
Design rationale
The environment separates setup from machine allocation and work to run. Why it works this way: Decisions.