Box Spec Guide
How Link reads a box spec, what its values mean and how it picks the machine. Each field is in the Box Spec reference.
schema = 1
name = "web"
version = 3
[machine]
cpus = { min = 2, max = 8 }
memory = { min = "4 GB", max = "16 GB" }
disk = { min = "40 GB", type = "balanced" }
tags = { team = "research" }
[machine.aws]
region = "eu-west-2"
size = "t3.large"
[machine.gcp]
region = "europe-west2"
memory = { min = "8 GB", max = "32 GB" }
spot = trueRead a Spec
Every key is optional. Left out, a key is the least that works, and an
empty file makes the box lnk box create <cloud> makes with no
flags. A box's setup isn't a key: each stage is a Sandbox
Spec
your setup script runs on the box, as Set a box up in
stages shows.
Files and Flags
lnk box create, lnk box size list, lnk box check, and lnk box spec show take the file as --spec FILE and each field as
a flag spelled as its key path, such as --machine.cpus 4 or
--machine.aws.region eu-west-2. A flag sets its key alone, as the
file's line would. A file is at most 64 KB. An unknown key, an empty
table, or a value that isn't one is refused when the file is read, the
error naming its line.
A Cloud's Own Table
A cloud's table, [machine.<cloud>], is named by the cloud's kind, as
lnk cloud list
says it: [machine.aws], [machine.gcp], or another adapter's. It
takes the same keys as [machine] and replaces them on that cloud, each
key whole, so [machine.gcp] memory above has no say from
[machine]'s. region and size go only there, since each names one
cloud's, and a cloud's table can't hold another table. A table for a
cloud the box isn't on has no say.
Which Wins
The cloud's table, then [machine], then Link's default. A flag sets
the key it names, so --machine.cpus 4 changes [machine] and
--machine.aws.cpus 4 changes AWS's table alone. --zone with
--cloud is the region of that cloud's table. lnk box create notes
a [machine] flag the cloud's table outranks: its own key, or its
size, which has its cpus, memory and GPUs built in.
Isolation Here
A box made here is isolated as lnk agent create's
agents are: in Link's sandbox, the default, in the sandbox spec
isolation.sandbox names, read once when the box is made, or directly
with isolation.no_sandbox, refused where this machine's agent policy
says unsandboxed = false. A cloud account's box is a machine of its
own, so it refuses the whole table before anything is made. This build
of Link has no VM provider, so a spec naming isolation.vm is refused
and nothing is made in a sandbox in its place.
Environment
env names an environment file for every placement. Creation captures
the checked file and its declared inputs once, before anything is
made. A box here sets it up on this machine, as lnk env setup here
does. A cloud box starts from the environment's image when it saves
stages, then runs its start stages and services on the machine. Each
box keeps its captured environment and starts it again at lnk box start, never reading its source again, as the machine
contract describes.
The lnk on the Box
From a file, [lnk] version can't be behind this computer's lnk, so
a spec someone hands you can't install a release with a known hole. To
mean a lower one, type --lnk.version yourself. Releases before 0.11.0
have no modules and are refused either way.
Values
What each [machine] key takes, and what the cloud makes of it.
A Count or a Range
A count or size alone means exactly that, as in cpus = 4. A range is
{ min = 2, max = 8 } with either end left out, but not both, and
min never over max. On the command line each end is its own flag,
--machine.cpus.min 2 --machine.cpus.max 8. A count is at most 4096.
A Size
Sizes are strings with their unit, as "8 GB", "512 MB" or "1 TB", and a bare number is refused. GB means GiB, as both clouds count
memory. On the command line it is 8GB.
GPUs
gpus = 1, or gpus = { min = 1, max = 2, model = "nvidia-l4" }. A model alone means at least one. Models are
nvidia-t4, nvidia-l4, nvidia-l40s, nvidia-a10g, nvidia-a100,
nvidia-h100, nvidia-h200 and nvidia-b200.
arm64
arch = "arm64" gets Ubuntu's arm64 image. The machine type is matched
among the cloud's arm64 ones as cpus and memory are, since the
default size is x86_64, or it is the arm64 size given. It has no
GPUs, because NVIDIA's images are x86_64. A size its cloud lists as
the other processor, such as t4g.small on an x86_64 box, is refused.
The Disk
disk.min is what the box gets, unless its image needs more. NVIDIA's
images for a box with GPUs are larger than 20 GB, so such a box gets
its image's size, said as it's made. disk.type is balanced or
fast, and a fast disk is billed for its speed too.
Spot
spot = true is cheaper, but the cloud may take the machine back. It
stops the box and never deletes it, so its disk stays and is billed.
lnk box list says the cloud stopped it.
Telling the Cloud Stopped It
AWS says so in the instance's state reason. Google Cloud doesn't, so
there it is a spot box found stopped that ran when this computer last
saw it, which lnk box stop on another computer looks like too, and
the list says both.
Starting Again
On AWS it is a persistent spot request, which starts the box again on
its own once AWS has the capacity. lnk box delete cancels the request
first, and cleanup cancels Link's requests whose box is gone. On Google
Cloud, lnk box start <box> starts it.
Tags
tags keys start with a lowercase letter, and keys and values are
lowercase letters, digits and dashes, at most 63 each. A box takes at
most 40 of yours in all. Keys starting lnk- or aws:, and Name,
are Link's or the cloud's, and refused. On Google Cloud they're labels.
Each tag is its own flag, --machine.tags.team research.
A Region
region on Google Cloud is a region or a zone in it. A region means
its first zone that's up.
Deadline
deadline = "4h" limits a box's lifetime, from one second through
seven days, and lnk box list shows it, its JSON too.
How Each Cloud Ends It
Google Cloud sets the instance's maximum run duration and deletes it at termination. AWS terminates on shutdown and installs a root-owned systemd timer at first boot to power off at the deadline. A process running as root can change that timer.
In an Image
lnk box image create leaves the timer out of the image, so a box made
from it never ends at the deadline of the box it was saved from.
How the Machine Is Picked
From the spec's CPUs, memory and GPUs, or its size, among what the
cloud has where the box is made (lnk box size list).
The Default Size
With no cpus, memory or gpus, the box gets the account's default
size: t3.small on AWS, e2-small on Google Cloud.
The Smallest That Fits
Otherwise it gets the smallest that fits, by CPUs, then memory, then GPUs. Memory is at least 2 GB when the spec says none, and a box has no GPU unless it asks. Between equals it takes the cheaper when the cloud gives a price, then the cloud's order: general purpose first, current generation, cheapest family first.
Room for an Agent's Memory
An agent's memory searches by meaning with an embedding model, a model
that turns text into numbers so notes that mean the same thing are found
together. That model runs on the box, beside the agent, and needs memory
of its own. Memory's default, qwen3-embedding, is Ollama's 8-billion
parameter model, about 4.7 GB. It won't fit the default size, an
e2-small on Google Cloud or a t3.small on AWS, each with 2 GB. Give a box that runs it at least
8 GB, such as an e2-standard-2 or a t3.large, or have the agent
search by words alone with [tool.memory] model = "none" in its spec.
lnk box create gcp --name gcp-1 --machine.memory 8GBA Machine Type
size wins. A machine type has its CPUs, memory and GPUs built in, so
a table giving size and any of those is refused. arch with size
must be its processor. A size the adapter doesn't list there, such as
an older generation or a GPU Link has no name for, is made as given,
with a warning, and the cloud says whether it has it.
When Nothing Fits
The error names the nearest on each side: "the smallest with 4 CPUs has 16 GB, over your max of 8 GB".
GPUs on Google Cloud
A box's GPUs are those built into its machine type (G2, A2, A3, A4), or
T4s attached to an N1 machine. Link names an N1 machine with T4s
<machine type>.nvidia-tesla-t4.<count>, such as
n1-standard-4.nvidia-tesla-t4.1, and size takes that name too. A
T4 box is made only in zones that have T4s.
NVIDIA's Driver
A box with GPUs gets Ubuntu with NVIDIA's driver: AWS's Deep Learning
Base AMI, or Canonical's accelerator image on Google Cloud. Both clouds
give a new account no GPUs until you ask them to raise its quota, and
lnk box create says where when the cloud refuses.
Plan for a Cloud
lnk box check --plan <kind> prints what a spec asks of a box in a
cloud of that kind instead of looking anything up, its table for that cloud laid over and every default filled
in: the request a job carries to the box that runs it.
lnk box check --plan aws --spec web.tomlWhat Spec Show Prints
lnk box spec show <box> prints the spec the box was made from, as
this computer kept it in boxes.toml, with any field flags laid over.
--json prints the same fields as JSON. Why it works this way:
Decisions.
What Its Cloud Pins
Its cloud's table pins what the cloud says the box is: its size and
region, and its disk, os and spot where they differ.
A Box From Before, or Elsewhere
A box made before specs, or on another computer, prints only what the
cloud keeps, and its [lnk] is left to the defaults. An [lnk] version behind this computer's lnk is left out too, so the file
reads back, and said on stderr with the --lnk.version that makes it
again.
Attachments
[attach] names existing resources the machine uses without creating
or deleting them, and its own boot disk remains disposable. Removal
keeps attached disks and addresses, and Link never formats a disk. An
AWS data volume also requires its subnet, in the same availability
zone.
Check Attachments First
lnk box check looks them up without making anything and says they're
present, or with --json prints {"attachments": "present"}. The
cloud refuses missing resources before launching the VM.
lnk box check gcp --spec service.toml