Boxes Guide
A computer in your own cloud, running lnk. Connect your AWS or
Google Cloud account once, and one command makes a machine there with
lnk on it.
lnk uplnk cloud connect awslnk box create awslnk box ssh aws-1lnk box listlnk box stop aws-1lnk box start aws-1lnk box delete aws-1What it needs
You need a Mac or Linux with OpenSSH, and your own AWS or Google Cloud
account. lnk up adds the modules, and lnk cloud connect offers
to install the cloud's CLI.
Boxes here
lnk box create here makes a box on this machine, with no VM and no
cloud account. A box here is a folder of its own,
~/Link/Boxes/<name>/home, which its commands start from. Box keeps its
record beside your cloud boxes in boxes.toml.
lnk box create here --name here-1lnk box ssh here-1Isolation is a separate choice, made with the same flags as
lnk agent create:
| Configuration | Flags | What runs the box's commands |
|---|---|---|
| Sandbox, the default | none, or --sandbox <spec> | This machine, inside the box's sandbox |
| Directly | --no-sandbox | This machine, with your own access |
Sandboxed or direct
A sandbox here is lnk sandbox run with the sandbox spec
given, read once when the box is made, or Link's own. Either way the box
writes its home. --no-sandbox is refused where this machine's agent policy
says unsandboxed = false, at the box's creation and again at each command.
Its commands
lnk box run, ssh and copy act in the home. start and stop
start and stop its environment's services. delete stops them and
removes the record, and removes the home only once you confirm.
lnk box user is refused inside a box here, since a box user is a login
on a machine of its own.
VM boxes
A VM (virtual machine) is a whole computer emulated by this one, with
its own operating system. Box makes no VM itself, and this build of Link
has no VM provider, so it takes no --vm. A box spec naming
isolation.vm is refused before anything is made, never made in a
sandbox instead.
VM providers
A VM provider is a module that answers Box's box.machine question
(Finding a VM Provider). Where one is installed and
this machine's owner requires a VM (vm_required), a box here is a VM
box from the host's default, as an agent's is. It refuses --sandbox
and --no-sandbox, since its guest sandboxes what runs in it.
Machine inputs
--env is an input that every placement captures once, before anything is made. A box here sets its environment up on this machine as lnk env setup here does, its stages in their sandboxes or directly with --no-sandbox. A cloud account's box takes --env, set up on the machine as Environments describe, and refuses --sandbox and --no-sandbox visibly, with no nested or native fallback.
Who owns a box
Boxes use your signed-in Link account when available; otherwise the local user and machine name identify their owner. Link login is optional.
What it costs
Boxes in a cloud account cost money, billed to your account by your cloud. Local Link adds no charge for them.
Connect a cloud account
A box is made in a cloud account you connect once, which keeps your buckets too: Cloud Accounts has connecting and disconnecting one.
Create a box
A box costs money, so create shows the machine it picked, its disk and
the price when the cloud gives one, then asks.
lnk box create awslnk box create gcp --zone europe-west1-b --machine.gcp.size e2-standard-4lnk box create aws --machine.cpus 4 --machine.memory.min "8 GB" --machine.memory.max "16 GB"A new box is Ubuntu 24.04 on x86_64 with a 20 GB disk and only SSH
open. It gets lnk, and what you run on it adds its own modules. lnk agent move aws makes a box itself when you have none in aws.
Installed programs
A box gets lnk, Secret and Sandbox. Account modules can be installed
separately; creating a box needs only its cloud account.
Run Your Own Build
--bundle makes the box from a bundle of your own checkout. Give it the
name of one lnk bundle
kept, such as devbox, which means the newest devbox it made, or the
bundle's folder by a path, wherever it is. A word alone is always a
kept name, so a folder of the same name here is ./devbox. That
bundle's own lnk, which trusts the signer you made it with, makes the
box and installs the bundle on it. Run from the bundle's bin/, its lnk
makes every box from the bundle without --bundle (a bundle's own programs).
lnk box create gcp --name gcp-1 --bundle devboxlnk box create gcp --name gcp-2 --bundle ~/builds/devboxThe box keeps the copy of the bundle it was given, and installs every
later module from it. A module that lnk box run, lnk agent move,
or a command typed on the box itself, such as lnk agent tool add, adds
there comes from your bundle, never Link's public releases, which hold
no build of your checkout.
Get into a box
lnk box ssh opens a shell or runs one command on a box, and lnk box run runs lnk there.
A login shell on a box finds lnk: setup adds ~/.lnk/exec/bin to the PATH in ~/.profile.
lnk box ssh
lnk box ssh gcp-1 -- uptime
lnk box run gcp-1 -- agent showLet people in
Box Users explains adding, listing, and removing Linux logins on a box. Each person gets a home and sandbox, and SSH shells, remote commands, and file transfers all enter that sandbox. Run user-management commands on the box as root, after preparing the person's public SSH key and sandbox file.
Forward home to a box
A box can send its traffic out through this computer, so sites see your
home address. Give lnk box forward a SOCKS proxy on this computer's
loopback, one that refuses this computer and its networks, and it
offers the box that proxy, on a Unix socket in its runtime folder or on
a port of its loopback:
lnk box forward gcp-1 --socket proxy.sock --proxy-port 1080lnk box forward gcp-1 --port 40780 --proxy-port 1080SOCKS is a protocol a program speaks to a proxy, asking it to connect
somewhere on its behalf. lnk box forward lasts until the SSH
connection drops.
Set it up your way
Describe the machine in a file, set it up with a script, and save the result as an image, and the next box is one command away.
Describe a box in a file
A box spec says the machine in a file, so the same file makes the same box, on any cloud you've connected.
lnk box size list aws --spec web.tomllnk box create aws --spec web.tomllnk box create gcp --spec web.toml --machine.spotlnk box spec show web-1 > web-1.tomllnk box spec show --machine.cpus 4 --machine.disk.min 40GBA box spec is a TOML file that describes the machine the way you would at a store.
# web.toml
schema = 1
name = "web" # its boxes: web-1, web-2, ...
[machine]
cpus = { min = 2, max = 8 }
memory = { min = "4 GB", max = "16 GB" }
disk = { min = "40 GB" }
[machine.aws]
region = "eu-west-2"The box gets the smallest machine that fits. The min is what it needs
and max the most you'll pay for, and the same file makes the best fit
on AWS and on Google Cloud. A flag wins over the file. Every field is in
the box spec.
The spec a box was made from
lnk box spec show <box> prints the spec a box was made from, with its
machine pinned for its cloud, so the file makes exactly that box there
(what it prints).
Set a box up in stages
A setup script sets a box up in stages: plain sh, each command in it
a stage, lnk box copy putting its files on the box, and its image
saved once by a hash of what made it.
lnk box copy web-1 clone.toml deps.toml build.toml setup
LNK_BOX=web-1 sh -e setup.shRun each stage that fetches or builds in a sandbox of its own on the box, so cloning reaches only GitHub, installing only the package registry, and building nothing. The sandbox costs nothing beyond the box.
box=${LNK_BOX:?}
lnk box ssh "$box" -- sudo apt-get update -qlnk box ssh "$box" -- sudo apt-get install -y python3-piplnk box run "$box" -- module add sandboxlnk box run "$box" -- sandbox check --ready --yeslnk box copy "$box" clone.toml deps.toml build.toml setuplnk box ssh "$box" -- mkdir -p app
lnk box run "$box" -- sandbox run --spec setup/clone.toml --yes -- git clone https://github.com/me/app applnk box run "$box" -- sandbox run --spec setup/deps.toml --yes -- python3 -m pip install --no-cache-dir --target app/.deps -r app/requirements.txtlnk box run "$box" -- sandbox run --spec setup/build.toml --yes -- sh app/build.sh# clone.toml: cloning reaches GitHub alone, as git, and writes ~/app and its .git
schema = 1
name = "clone"
version = 1
[files]
write = ["~/app"]
write_dot_files = ["~/app"]
[internet]
hosts = ["github.com"]
[commands]
allow = ["git", "/usr/lib/git-core/"]# deps.toml: installing reaches PyPI alone, never GitHub
schema = 1
name = "deps"
version = 1
[files]
write = ["~/app"]
[internet]
hosts = ["pypi.org", "files.pythonhosted.org"]
[commands]
allow = ["python3"]build.toml is the same with no [internet], allowing sh and
python3. A spec's sections are in the
sandbox docs.
A stage that fails
sh -e stops at the first stage that fails. The stages before it ran,
so fix the command and run the rest by hand, or start again on a new
box. The script can make the box itself, with lnk box create aws --name "$LNK_BOX" --yes as its first stage.
Folders a stage writes
Write lnk box copy's folder without a ~, which your shell would turn
into this computer's home folder. A stage's sandbox makes a folder its
spec writes that isn't there yet, so mkdir -p app above only makes it
sooner. A stage can't write a dot folder in your home, such as ~/.cache, so keep a stage's
caches in its own folder or turn them off, as --no-cache-dir does.
A stage keeps the dot files that run outside it read only at the top of
each folder it writes: .git, .envrc, .vscode and .idea. On Linux
it holds an empty one in place of each that isn't there, so git clone
into the folder finds it not empty. The clone stage names the folder in
write_dot_files, so cloning writes the repository's .git, and the
stages after it keep that .git read only.
Save a box as an image
An image is a box's disk, kept in your cloud account so new boxes can start from it.
lnk box image create web-1 web-readylnk box image list awslnk box image delete web-ready awsSaving takes a few minutes and needs a running box with no agent on it,
because an image would carry the agent to every box made from it. The
box's lnk is signed out first, so the image holds no login, and the box
is stopped while its disk is saved, so nothing is saved half-written. It
then starts again, and in a terminal lnk signs it in again: open the
link it prints.
Secrets it refuses
Saving refuses a box holding secrets where they're usually left, and lists what it found (where it looks). Remove them, then save again.
What it costs
The image keeps a copy of the disk in your account, billed every month by its size until you remove it. On AWS it's an AMI and its snapshot, in the box's region, and on Google Cloud it's an image in the project.
Create a box from an image
A box from an image starts with that image's disk, and gets its own
machine ID, SSH host key and lnk login, as any new box does.
lnk box create aws --image web-readylnk box create aws --image web-ready --spec web.tomlOn AWS, a box from an image loads each part of its disk from the image's snapshot the first time it's read, so its first reads are slower than a stopped box's.
Where it's made
The box is made where the image is, in its AWS region or any zone of the
Google Cloud project. Its disk is at least the image's, and lnk says so
when that is more than you asked for. It keeps the image's processor,
lnk and SSH keys.
Reuse an image while what made it stays the same
An image saved with a hash of what made it is found again by that hash, so a script saves it once.
lnk box image create build-1 app-3f2a9c --hash 3f2a9clnk box image list aws --hash 3f2a9clnk box create aws --name web-1 --image-hash 3f2a9cThe hash is yours to make, from your setup script, its specs and the lockfile its dependencies come from, so a change to any of them makes a new hash. A script can then save the image once and make every later box from it:
hash=$(cat setup.sh clone.toml deps.toml build.toml requirements.txt | shasum -a 256 | cut -c1-32)lnk box image list aws --hash "$hash" --json > images.jsonif [ "$(cat images.json)" = "[]" ]; then
lnk box create aws --name build-1 --yes
LNK_BOX=build-1 sh -e setup.sh
lnk box image create build-1 "app-$(printf '%s' "$hash" | cut -c1-8)" --hash "$hash" --yes
lnk box delete build-1 --yes
filnk box create aws --name web-1 --image-hash "$hash" --yesOn a box from the image, only what changed since needs a stage, such as
a git -C app pull in the clone's spec, then the dependencies' stage
again.
Attach existing resources
A box spec's [attach] names a preexisting network, identity,
address and disks. They are checked before launch and survive
removal. The box spec gives
each cloud's names. lnk box list --tag project=research --json queries
all owners and regions; add --cloud <cloud> to query one account.
Removal by immutable cloud ID uses lnk box delete --id <id> --cloud <account> --zone <region-or-zone> --yes; an already gone VM is done.
See, stop or delete
A stopped box still bills for its disk, and removing the box deletes the disk too.
See your boxes
lnk box list shows every box tagged as yours, with its account, place,
size, address and state.
lnk box listlnk box list --refreshlnk box list --all-regionslnk box list --herelnk box list aws --tag project=researchlist asks each connected account for the boxes tagged as yours, finding
those made on other computers, and --refresh asks each box's state now.
On AWS it looks in your boxes' regions, or every enabled region with
--all-regions or when it knows none, naming a region your login can't
reach. --here asks no cloud, and --tag finds boxes by tag across owners.
Show One Box
lnk box show reads the saved record for one box, including its last observed
address, size, placement, and state. It asks no cloud, so use lnk box list --refresh first when you need a fresh provider observation.
lnk box show aws-1Stop, start or remove a box
A stopped box keeps its disk and comes back at a new address; a removed one is gone with its disk.
lnk box stop gcp-1lnk box start gcp-1lnk box delete gcp-1lnk box delete gcp-1 --yesLimit a box's lifetime
lnk box create aws --deadline 4h --yes sets a maximum lifetime;
deadline = "4h" is the box spec's equivalent. A deadline is at most
seven days. AWS installs a persistent root-owned timer and terminates
on shutdown. Google Cloud uses its own run limit with deletion, at
least thirty seconds, and can begin deletion up to thirty seconds
after the limit. lnk box list shows the absolute deadline.
Get into your boxes from a new computer
Sign in to the same Link account and connect the same cloud account, and the new computer finds your boxes by their tags.
lnk cloud connect awslnk box listlnk box ssh aws-1The first connection pins the box's host keys from the cloud, lets this
computer's SSH key in through your account, and has the box trust this
computer's SSH certificates. Then the key goes. Each computer's
certificate authority has the comment lnk-ca <machine id> <machine name>, so you can find and remove a lost computer's on a box
(Certificates).
Where things live
What Link keeps for your boxes, on this computer and on each box; every file is on Configuration.
~/.lnk/safe/clouds/accounts.tomlholds your accounts, access keys included. On a Mac, secrets are in the Keychain.~/.lnk/safe/boxes/boxes.tomlis this computer's copy of your boxes, each with the spec it was made from. The clouds hold the record, by tags. A box here is recorded only there, with its home and its captured sandbox spec, which~/.lnk/safe/boxes/here/<name>.tomlholds while its commands run.~/Link/Boxes/<name>/homeis a box here's home, your data, kept until you confirm its removal.~/.lnk/safe/boxes/id_ed25519andknown_hostsare Link's SSH key for boxes, and their host keys.lnk box key showprints the key's public half, for a machine that lets you in by it, andlnk box key show --secret-filewhere its secret half is. A box takes it only with a certificate.~/.lnk/safe/boxes/ssh-ca.pubandcerts/are this computer's SSH certificate authority and the certificates it signed, its secret in the Keychain on a Mac, else inssh-ca.~/.lnk/safe/machine.tomlon a box holds its machine ID and name./etc/lnk/users/<name>/on a box is root's record of a user: their folder and key, their sandbox's spec and the key's one line;/usr/local/lib/lnk/holds the programs their sessions run.
More about it
Every flag is in lnk cloud <command> --help and lnk box <command> --help. Security has what Link guarantees and its gaps,
Decisions why it works this way, and
Troubleshooting what to do when a box won't.