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.