Env Spec
An environment spec says what a machine has before work starts: its OS, where work starts, the values every run is given, the stages that set it up and the image they make, and the services it runs. The env spec is TOML, given to a command that reads it as a file, and a field flag sets the field it names, overriding the file. Its JSON Schema is env.schema.json.
Use It
Give lnk env check, lnk env create, lnk env reset, lnk env setup, and lnk env image create a env spec as a file, and set any field below with its field flag, which overrides the file. lnk env spec show prints the spec as it is read.
Every Option
Every field the reader takes, with an example value.
kind = "env"
schema = 1
name = "web"
os = "ubuntu-24.04"
version = 1
workdir = "app"
[secrets]
names = ["GITHUB_TOKEN"]
sealed = ["OPENAI_API_KEY"]
[[service]]
name = "cache"
reset = "redis-cli flushall"
run = "redis-server --port 6379"
sandbox = "cache.toml"
[service.ready]
port = 6379
timeout = "30s"
[[service]]
name = "health"
run = "./health"
user = "redis"
[service.ready]
run = "redis-cli ping"
timeout = "30s"
[[stage]]
inputs = ["Cargo.lock"]
name = "build"
run = "cargo build"
sandbox = "build.toml"
timeout = "30m"
when = "image"
[[stage]]
name = "serve"
run = "./serve"
user = "builder"
when = "start"
[[stage]]
name = "together"
[[stage.parallel]]
name = "test"
run = "cargo test"
sandbox = "build.toml"
[variables]
LOG_LEVEL = "info"name
Type text · Flag
--spec.name
Its name, which its boxes and images are named by.
Lowercase letters, digits and dashes, starting with a letter, at most 30 characters.
os
Type one of
ubuntu-24.04,ubuntu-22.04,debian-13,macos· Flag--os
The OS its machines run; none, any, and an image for each.
ubuntu-24.04 or ubuntu-22.04, as a box spec's. An OS named
refuses a box or here running another, a Mac included.
secrets
Type a table · Flag
--secrets
The secrets its runs are given, by name: their values are this machine's, never the file's.
Each is given to the environment only once you've said yes to that
file (lnk env approval add), by its real path, its name and the
secret's ID, so a copy or a move asks again, and field flags over
it, another spec than the one you said yes to, ask for that run
alone. A missing yes is refused before the file runs, naming the
secret; lnk env check reads the file without one. Stages and jobs
get the values, services variables alone, and an image build none,
since an image keeps what its stages write.
names
Type a list, each text · Flag
--secrets.names
Secrets given to runs as plain variables, by name.
Each is created without --host; services and image builds get
none of them.
sealed
Type a list, each text · Flag
--secrets.sealed
Secrets the sandbox's proxy adds to requests for the host set with each value, by name. What runs never has them.
Each is created with --host; stages get a placeholder, and the
proxy puts the real value in only for that host.
service
Type a list, each a table · Flag
--service
The services it runs beside its stages, each kept running until it's stopped.
name
Type text · Flag in
--service, whole elements
Its name, which lnk env reset and previews name it by.
Lowercase letters, digits and dashes, starting with a letter, at most 30 characters, unique among the file's services.
ready
Type a table · Flag in
--service, whole elements
When it's ready, which a start waits for: a port taking a connection, or a command passing.
port
Type a whole number from 1 · Flag in
--service, whole elements
Ready once this port of the machine's loopback takes a connection.
run
Type text · Flag in
--service, whole elements
Ready once this command line, in the service's sandbox, passes.
timeout
Type text · Default
"1m"· Flag in--service, whole elements
How long it's waited on before the start fails, from 1s to 24h.
reset
Type text · Flag in
--service, whole elements
A command line putting it back as the image had it, for lnk env reset; none, there's nothing to run. A root service's reset runs
as root.
run
Type text · Flag in
--service, whole elements
A command line, for sh -c, that runs until it's stopped, once
its ready has passed.
sandbox
Type text · Flag in
--service, whole elements
The sandbox spec it runs in, from the file's folder.
Required for an ordinary service; one run as root or a named user
of the box has that user's boundary instead.
user
Type text · Flag in
--service, whole elements
Who it runs as; none, the machine's user.
root, Docker included, only on a box of its own. A service gets
the variables, and one ready on a port serves the machine's
loopback, which a sandbox reaches only where its [localhost] ports lets it.
stage
Type a list, each a table · Flag
--stage
The stages, in order: the first that fails ends the build, the start or the job, naming it.
A stage is one command, or a named group of commands run together
(parallel).
inputs
Type a list, each text · Flag in
--stage, whole elements
Files, from the file's folder, whose contents count in the image's hash.
So a dependency lockfile makes a new image when it changes.
name
Type text · Flag in
--stage, whole elements
Its name, unique among the file's stages and parallel members.
Lowercase letters, digits and dashes, starting with a letter, at most 30 characters.
parallel
Type a list, each a table · Flag in
--stage, whole elements
Its members, started together, each in its own sandbox, its output lines starting with its name.
A failing member lets its peers finish, then ends the build or job
with the first failing member's code, and later stages don't run.
A member is never a group itself, and a group has at least one. In
an environment, a group's members share their when, and its image
hash counts the grouping, the members' order and the group's
timeout.
run
Type text · Flag in
--stage, whole elements
A command line, for sh -c.
sandbox
Type text · Flag in
--stage, whole elements
The sandbox spec it runs in, from the file's folder.
Required for an ordinary stage; a root stage, or one run as a named user of the box, has that user's boundary instead.
timeout
Type text · Flag in
--stage, whole elements
How long it may run; none, only the build's or the job's limit.
From 1s to 24h, such as 30s, 10m or 2h. The first limit
reached wins, and a stage past its own fails the whole build or job.
user
Type text · Flag in
--stage, whole elements
Who it runs as; none, the machine's user.
root runs outside any sandbox, only while an image is built on a
box made for it, with no sandbox and never at every start. A user
added by lnk box user add runs in their own sandbox and home, with
the variables and no sandbox, and must exist on the box. Naming
the machine's own user is leaving it out.
when
Type one of
image,start· Default"image"· Flag in--stage, whole elements
When it runs: while the image is built (image), saved in it, or at
every start (start), never saved. A root stage runs only while an
image is built.
variables
Type a table by name, each text · Flag
--variables
Text given to every run as it is, by name: never a secret.
Names are capital letters, digits and _, none of Link's (LNK_...,
PATH, HOME, USER, LOGNAME, SHELL, TERM, LANG, TZ). A
name like a secret's, such as API_TOKEN, is refused: a private
value is a secret, named under [secrets].
<name>
Type text · Flag
--variables.<name>
version
Type a whole number from 0 · Flag
--spec.version
The environment file's version this Link reads, 1.
It describes the file's shape, independently of the repository or program versions its stages install.
workdir
Type text · Flag
--workdir
Where work starts, from the home folder; none, the home folder.
A relative folder, without ... Start stages, services, their
ready and reset, job stages and agents begin here, and it is an
agent's files folder. Image stages begin at home, so a clone can
make this folder; a later run starting before it exists fails and
names it.