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 up
lnk cloud connect aws
lnk box create aws
lnk box ssh aws-1
lnk box list
lnk box stop aws-1
lnk box start aws-1
lnk box delete aws-1

What 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-1
lnk box ssh here-1

Isolation is a separate choice, made with the same flags as lnk agent create:

ConfigurationFlagsWhat runs the box's commands
Sandbox, the defaultnone, or --sandbox <spec>This machine, inside the box's sandbox
Directly--no-sandboxThis 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 aws
lnk box create gcp --zone europe-west1-b --machine.gcp.size e2-standard-4
lnk 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 devbox
lnk box create gcp --name gcp-2 --bundle ~/builds/devbox

The 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 show

Let 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 1080
lnk box forward gcp-1 --port 40780 --proxy-port 1080

SOCKS 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.toml
lnk box create aws --spec web.toml
lnk box create gcp --spec web.toml --machine.spot
lnk box spec show web-1 > web-1.toml
lnk box spec show --machine.cpus 4 --machine.disk.min 40GB

A 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.sh

Run 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 -q
lnk box ssh "$box" -- sudo apt-get install -y python3-pip
lnk box run "$box" -- module add sandbox
lnk box run "$box" -- sandbox check --ready --yes
lnk box copy "$box" clone.toml deps.toml build.toml setup
lnk box ssh "$box" -- mkdir -p app

lnk box run "$box" -- sandbox run --spec setup/clone.toml --yes -- git clone https://github.com/me/app app
lnk box run "$box" -- sandbox run --spec setup/deps.toml --yes -- python3 -m pip install --no-cache-dir --target app/.deps -r app/requirements.txt
lnk 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-ready
lnk box image list aws
lnk box image delete web-ready aws

Saving 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-ready
lnk box create aws --image web-ready --spec web.toml

On 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 3f2a9c
lnk box image list aws --hash 3f2a9c
lnk box create aws --name web-1 --image-hash 3f2a9c

The 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.json
if [ "$(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
fi
lnk box create aws --name web-1 --image-hash "$hash" --yes

On 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 list
lnk box list --refresh
lnk box list --all-regions
lnk box list --here
lnk box list aws --tag project=research

list 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-1

Stop, 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-1
lnk box start gcp-1
lnk box delete gcp-1
lnk box delete gcp-1 --yes

Limit 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 aws
lnk box list
lnk box ssh aws-1

The 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.toml holds your accounts, access keys included. On a Mac, secrets are in the Keychain.
  • ~/.lnk/safe/boxes/boxes.toml is 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>.toml holds while its commands run.
  • ~/Link/Boxes/<name>/home is a box here's home, your data, kept until you confirm its removal.
  • ~/.lnk/safe/boxes/id_ed25519 and known_hosts are Link's SSH key for boxes, and their host keys. lnk box key show prints the key's public half, for a machine that lets you in by it, and lnk box key show --secret-file where its secret half is. A box takes it only with a certificate.
  • ~/.lnk/safe/boxes/ssh-ca.pub and certs/ are this computer's SSH certificate authority and the certificates it signed, its secret in the Keychain on a Mac, else in ssh-ca.
  • ~/.lnk/safe/machine.toml on 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.