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 listlnk module show telegramlnk module add telegramlnk upgradeInspect 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 pick | Modules | lnk groups |
|---|---|---|
| agents | agent, harness, their tools and needs | agent, sandbox, mcp, man |
| boxes | box, cloud | box, cloud |
| documentation | man | man |
| models | model | model |
| storage | storage | storage |
The rest come when you need them:
- A harness (
claude,codex,deepseek,hermes,openclaw) when youlnk agent harness setit. - A connection module (
telegram,slack,discord,signal) when you connect one. memory-toolwhen you turn on your agent's memory (lnk agent memory start).web-toolwithlnk module add web-tool, for Link Web.browser-toolwithlnk agent tool add browser, for Link Browser.desktop-toolwithlnk agent tool add desktop, for Link Desktop.awsorgcpwhen you connect that cloud.secretwhen you first keep a secret (lnk secret create), for an agent to be granted it (Secrets).
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 listlnk module add telegramlnk module remove storageFor 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.
Add a module from outside Link
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-examplelnk module add --url https://github.com/example/lnk-example --yeslnk module listlnk module remove exampleaddinstalls the module from the repository's latest release. The first time, it shows the release's key and asks, andlnkthen 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 upgradeupdates 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-describeas 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 moveto 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 upgradelnk upgrade 0.14.0lnk upgrade --checkEach 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 --yesAfter 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 --yesThe 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 uninstalllnk uninstall --yeslnk uninstall --yes --delete agentslnk uninstall --yes --allWhat 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 helplnk help storagelnk help storage pushlnk module listWhen 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.
Move the Link folder
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/LinkLink 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.
A Link folder that moved without lnk
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.