Modules Guide

lnk is a small core, and each part of Link is a module, so you install only the parts you use. The core only installs, runs, updates and removes them. You need lnk, which is free and which Install covers, picking your first ones.

lnk module list
lnk module show telegram
lnk module add telegram
lnk upgrade

Inspect a Module

Use lnk module show telegram to see whether the module is installed and what it does. For an outside module, the same command shows its repository and trusted signer's fingerprint. An unknown name is refused with a pointer to lnk module list; inspecting a module installs nothing.

What each choice installs

Picking a part installs only its modules and what they need, and a few more come when you use them. The agents choice's tools are code-tool, file-tool, run-tool and scheduler-tool, and it needs sandbox, mcp and man.

You pickModuleslnk groups
agentsagent, harness, their tools and needsagent, sandbox, mcp, man
boxesbox, cloudbox, cloud
documentationmanman
modelsmodelmodel
storagestoragestorage

The rest come when you need them:

Add or remove a module

lnk module lists, adds and removes modules, each with the modules it needs, and lnk offers a module when a command needs one.

lnk module list
lnk module add telegram
lnk module remove storage

For a released lnk, add installs from its own version's release and includes required modules. For example, agent needs sandbox and mcp, bucket-store needs storage, and aws, gcp and box need cloud. A source-built lnk builds modules from its checkout instead (Source Installation).

What Counts as Installed

add skips a module only when its program is already beside lnk, in the folder add installs into. A program of the same name elsewhere on your PATH, such as a build from source in a checkout's target/debug, doesn't count, so add still installs its own from the release lnk reads: the one LNK_RELEASES_URL names, else the bundle lnk runs from, else this machine's copy of the release lnk is, as a box made from your own build keeps, else Link's. lnk runs the program beside it first, so the one add installed is the one run.

Remove a Module

remove also removes modules that require the named module, including indirect dependents. For example, remove sandbox removes agent and stops its agents first. Recommendations are optional: remove agent keeps its harness adapters and connections, which recommend it, and keeps sandbox, which it requires. Removing a module stops what it runs and keeps its saved data.

A module a command needs

Run a command whose module you don't have, and lnk offers to install it. Outside a terminal, typed or in your script, it installs it without asking and says so: the command named what you wanted. The same goes for a module it needs that isn't installed, such as cloud for box or sandbox for agent.

Modules that go together

Some modules go with others: a box with sandbox, Link Harness with memory-tool, web-tool and measure. lnk up installs a use's modules and what they need, never these. The first command of a module whose companions you don't have asks once in a terminal; a no is kept in ~/.lnk/safe/modules/offers.toml and not asked again, and lnk module add adds one later. Without a terminal it says once what adds them. Link Harness's scheduler, run, file and code tools are in the agents choice beside it, so they come with it.

A feature that needs another module

A feature that needs another module installs it the same way: lnk agent backup and restore the storage module, lnk agent move <cloud> the box and cloud modules, a bucket in a cloud account (not a folder's) the cloud module. In a terminal it asks first, naming everything it will install; a command naming the module itself (lnk agent connect slack, lnk agent harness set hermes, lnk agent tool add web) doesn't ask. A module's own call to lnk underneath installs nothing: a missing module there is named, with the command that installs it.

A module Link doesn't come with comes from its own GitHub repository, signed by its maker's key. A harness adapter is one example. The harnesses Link comes with are in Use another harness.

lnk module add --url https://github.com/example/lnk-example
lnk module add --url https://github.com/example/lnk-example --yes
lnk module list
lnk module remove example
  • add installs the module from the repository's latest release. The first time, it shows the release's key and asks, and lnk then keeps the repository and the key in ~/Link/Safe/settings.toml. With --signer ssh-ed25519 ..., it trusts the key you got from its maker instead of the one the release offers, and refuses a release signed by any other.
  • lnk upgrade updates it from the same repository, and only with a release signed by that key.
  • Only a module can be added this way: its lnk-<name> must answer --link-describe as itself, a module and not a program of its own, and its name can't be one of Link's modules'. A harness program is one (Harness programs).
  • It runs as you, like any program you install. Link's sandbox confines the harness it installs, not the module itself (Security).
  • lnk agent move to a box adds it there from the same repository, trusting only the key this computer trusted.

Upgrade

lnk upgrade updates lnk and every installed module, only from a release whose signature it checked.

lnk upgrade
lnk upgrade 0.14.0
lnk upgrade --check

Each release is checked against its signature first, and if anything fails, what you have stays as it was. Its signed version is read before anything else: a release of the version you have, every module included, downloads nothing.

Checking Without Installing

lnk upgrade --check installs nothing. It says whether a newer lnk is out, then checks each module added with lnk module add --url against its own repository's latest release, signed by the key you trusted, and names each newer one. Each part is checked whatever another found. When one can't be made, such as a release host that doesn't answer, it says why, and the check fails after naming what it did find.

Your Yes

lnk upgrade first asks the release's own programs what they will change in the files Link writes. Each tries its conversions without writing, so a file that won't convert stops the upgrade before anything is installed. It shows what it installs, each file it converts to the new release's shape and each setting that moves to its new owner, and asks once. A no installs nothing. History, such as conversations and logs, is never rewritten, and a spec you wrote is only offered for lnk spec convert. With no terminal to ask on, the upgrade is refused unless --yes agrees ahead.

lnk upgrade --yes

After your yes it installs the release, and each program then makes only the changes you agreed to (Upgrades). A file holding a setting whose new owner isn't installed is kept as it was and named, and the other changes go on. An upgrade stopped partway finishes when lnk upgrade runs again, removing a renamed or removed module's old program it left.

Root's Copies

A Linux machine keeps root's own copies of two module programs in /usr/local/lib/lnk, which root's services run: the keeper of your secrets, lnk-secret, and a box's worker launcher, lnk-sandbox. A new lnk can't talk to an old keeper, so lnk upgrade compares each copy with your new one and, where they differ, offers to copy it again with sudo, by lnk secret keeper create and lnk sandbox workers --install. --yes copies them without asking. Off a terminal, the upgrade names both commands as its next steps instead.

lnk upgrade --yes

The list of copies and their commands is root_programs.toml, beside the upgrade's code.

Update Notices

lnk up and lnk agent show show ordinary notices of a newer release at most once a day, and never with --json, off a terminal, or with LNK_UPDATE_NOTICE=off. Critical security advisories remain visible under those settings. Notices never wait for the network: a day after the last check, they start lnk upgrade --check in the background, and the next command says what it found.

Release Notes

After lnk upgrade, the new lnk's first command prints what changed in each release since the one you had, once, and stays quiet afterward. Like an ordinary notice, the notes wait for a command on a terminal, without --json or LNK_UPDATE_NOTICE=off (Release notes).

On a Box Made From Your Own Build

A box made from a bundle of your own build keeps a copy of that one release, and its lnk follows the copy. There lnk upgrade --check says the copy holds no later release, and the box gives no notice of one. lnk upgrade to any other version says the same and stops, naming how the box gets another build: on your own machine, lnk box create <cloud> --bundle <bundle> makes it again from a new bundle.

Installed with Homebrew

Installed with Homebrew, lnk upgrade refuses, saying lnk was installed with Homebrew and to use brew to change it: brew upgrade lnk upgrades it.

Uninstall

lnk uninstall has each module stop what it runs, such as your agents and their sandboxes, and removes lnk and its modules. Everything Link kept stays unless you pick it, so installing again picks it up.

lnk uninstall
lnk uninstall --yes
lnk uninstall --yes --delete agents
lnk uninstall --yes --all

What each part takes

Installed modules report the parts they keep before you confirm removal. Common examples are agents, your agents, their memory, settings and keys, and what agents that left kept (~/.lnk/data/agents/move); personal, your files in ~/Link/Files; buckets, bucket settings and encrypted buckets' passwords; clouds, cloud keys and Link's SSH key and authority for your boxes; and rest, everything else in ~/.lnk and ~/Link. --all picks all of them.

Before you pick a part

Move an agent you want to keep to another machine first with lnk agent move, because agents deletes its memory and conversations. personal deletes files you never pushed to a cloud, and buckets deletes the only copy of encrypted buckets' passwords. clouds leaves your boxes running, and billing. rest takes folders you made in ~/Link too. On a Mac, each part's Keychain items go with it.

Installed another way

Installed with Homebrew, it prints the command that removes the programs. Installed with cargo, it prints cargo uninstall with the crates cargo installed them from, and deletes any it doesn't track.

Get help

lnk help lists every command, and says what each one takes.

lnk help
lnk help storage
lnk help storage push
lnk module list

When a command fails, lnk issue create turns the failure into a bug report with what's private scrubbed out, ready to paste, and lnk issue create --open fills in the bug form in your browser.

Where things live

Link keeps everything in two folders. The Link folder, ~/Link, is yours: your files in Files, your agents' in Agents, and what you edit that steers Link in Safe. ~/.lnk is this machine's: its settings and credentials in safe, lnk and its modules in exec/bin, the one PATH entry, and the rest in data. Outside the two folders are only the system's registrations, services and the PATH line in your shell's startup file.

See and move them

lnk folder list shows where each location is on this machine, lnk folder set moves one, and lnk folder create makes a new, empty Link folder. Where Link Keeps Things follows a secret and an agent through these folders and lists every location.

Every path Link stores in the Link folder is relative to it, so the folder can move anywhere in your home folder:

lnk folder set link ~/Documents/Link

Link moves it, records its place in the map, ~/.lnk/safe/map.toml, and points what your agents' harnesses keep at the new place: each path into the old one in their settings and state is rewritten, as it is when an agent moves to another machine. When you moved it yourself, the same command points Link at it.

When the Link folder isn't where it was, the next lnk command asks where it went, or whether to make a new one (lnk folder create). It never searches the disk.

More about it

What to do when a module won't install or update is in Troubleshooting. What's checked before anything installs is in Security. Why it works this way is in Decisions. How to build a module is in Modules under Developing.