Architecture Guide
lnk is a small core that runs a module for each part of Local Link,
and every agent runs in Link's sandbox, which lets it touch only what you
allow. This page is how the code is laid out and where new code goes,
and Our Mission and
Decisions say why it's built this way.
The core and its modules
A user installs the core alone with install.sh, and lnk up asks which
modules to add (Modules).
- A module is its own program,
lnk-<name>, next tolnk, andlnk <group> ...runs it, the waygitrunsgit-<name>. What a user installs is the executable that runs, without linking every other module into it. - The core only installs, runs, updates and removes modules. New behavior goes in a module, never the core.
- The core knows each installed program by what it describes through the versioned module protocol: its commands, kind, requirements and documentation. The core's own settings: Configuration.
- The command line routes an operation to the program that declares it, the release registry supplies installation choices and upgrade dependencies, and removal combines the state declarations installed programs return.
- Modules use each other only by running
lnk <command>and reading a documented output (Module Contracts). They never link each other's code or read each other's files. - Each of Link's modules is released as its own signed archive at the core's version. So are Link Harness, Link's tools (Link Memory) and the OpenClaw, Hermes, and DeepSeek Harness adapters, built from their own members. A harness from outside Link is released from its own repository, signed by its own key.
- Code goes in the module whose purpose it serves, and a module's purpose is its name. Before adding code to a module, ask whether you would still use this code without installing the module it serves, and whether this module has to know another's files, API or quirks. If either is yes, the code goes in the module it serves.
- A capability several modules need has one owner. Callers use that provider's commands or shared contract rather than copy its behavior. The test worked through is Where code goes: the seam test.
Layout
Repository Organization owns the folder tree, component ownership and layer declarations. Keep placement decisions there, while this guide describes the interfaces and runtime behavior.
Kinds
The Developer Glossary defines Link roles and Rust build units. Repository Organization explains how those roles appear in source folders and generated README headings.
Dependency rules
What a crate may depend on, and where what it declares lives:
- Cross-owner business logic uses the provider's owner-local contract. A contract's transitive graph contains no implementation or fixture. Generic core code and neutral libraries contain no domain contracts.
- Standalone composition declares exact importing modules and optional hosted features in Cargo metadata, rather than being a blanket exception for an application.
- The core links generic protocol and neutral packages. Its registry, routing, installation menu and removal behavior derive from descriptors.
- Neutral top-level packages have multiple subjects using them or a core consumer. Helpers owned by one subject stay beneath that owner.
- Cargo owns identity, binaries, versions and compile dependencies.
module.tomlowns operational requirements,actions.tomlowns commands, runtime arguments and their help, andtypes.tomlowns every shape, spec kinds among them. Rust is generated from these declarations, and Markdown owns authored explanations. - Runtime command requirements are distinct from compile dependencies. Executing another program names its command and typed option bindings; those requirements propagate on the executing platform.
- Tests never provision an engine just because the adapter can install it. Every checkout owns its build output.
- A released crate never builds with one a release holds back
(
released = false), though its tests may.
See Components for the
schemas and commands. A new crate goes in the workspace's
members; shared local paths are declared once in workspace.dependencies.
Where does new code go?
Prefer a new module over growing the core or another module, and keep crates small and names literal. Adding a module covers how, and each list below says, for what you're adding, the folder it goes in.
Account API Client
The API Client
owns the typed client and schemas for account operations. A route or
field starts in packages/api/schemas/account.yaml, then its client
function in packages/api (link-api). Types are generated from the
schema at every build. The client holds no credential. Its caller
hands it one.
Models and harnesses
The models an agent runs on, and the harnesses that run it:
- Finding, serving or managing models:
modules/agents/model. - Installing, configuring, running or switching harnesses:
modules/agents/agent. - Link Harness (its turns, its conversations, its window, calling
tools):
modules/agents/harnesses/link/, beside the core in the workspace, with its pages (modules/agents/harnesses/link/docs/agents/link/). The core's tests run on the mini harness (modules/agents/harnesses/mini), and every harness passes the conformance kit (modules/agents/harnesses/portability/conformance). - What the adapter contract asks of every harness:
modules/agents/harnesses/portability/contract(link_harness_contract::harness), answered by Mini Harness and checked by the conformance kit.
Support for one harness
Support for a harness from outside Link is its own repository, not this
one: an lnk-<name> answering the adapter commands in
link_harness_contract::harness (with contract), released and signed
with its own key, and added with lnk module add --url <url>. It runs
sandboxed with HOME set to the harness's home folder, so it writes
everything under link_files::home_dir(). What is specific to it is
its adapter's answer through the contract (Adding a
harness).
The harnesses Link comes with
The adapters Link comes with (OpenClaw, Hermes, and DeepSeek Harness) are
named in KNOWN (harness settings) and nowhere else under
src/ (architecture.rs).
An agent's moves, routes and connections
Where an agent's traffic leaves from, how it moves between machines, and the connections people text it on.
Where an agent's traffic leaves from
Where an agent's traffic leaves from, and the filtering proxy: modules/agents/agent decides which upstream
(settings.upstream, moving.rs). The sandbox module holds the proxy
(proxy.rs): a sandbox in its own network, with Link's proxy as its
only way out.
Moving an agent between machines
Moving an agent (lnk agent move) is modules/agents/agent
(moving.rs, transfer.rs, hosted.rs), plus each harness adapter's
state; the stream's format, each file's hash and what the other end
holds (have) are in link_agent_contract::moving. Two phases: a copy
while the agent answers, then a switch of what changed, the agent
paused (lnk agent pause).
How a move travels
One machine's lnk agent state-send is piped into the other's receive over
SSH (lnk box run), or into a cloud account's adapter when it hosts
agents (agent-receive, agent-send in link_cloud_contract).
Support for one connection
Support for one connection (Telegram, Slack, Discord, ...), where you
talk to your agent, is a new module in a folder of its own beside the
core, interop/agents/connections/<connection>/ (lnk-<connection>),
answering connect, describe and rule in
link_connection_contract, which make the bot, pair its owner and say
what the harness keeps of it. Declare its kind in module.toml and
update each adapter that speaks it. The harness module names no
connection (Adding a connection).
A connection in the core's tests
A core build compiles and tests no connection
(why):
the core's own tests that need one run the connection fixture
(tests/fixtures/connection, lnk-connection-fixture) against its fake
service (link_harness_conformance::fixture_connection).
Tools, memory and stores
The tools an agent calls, its memory, and where its conversations are kept:
- A tool for agents (an MCP server any harness calls), or Link
Memory (what it indexes, its search, its MCP tools):
modules/agents/tools/, with pages beside each tool.lnk-memory-tool serve <folder>is an MCP server over stdio that reads only its folder and never follows a link out of it. - Support for one memory engine: a module of its own (Link's is in
modules/agents/tools/) answeringinstall,launch showandserve-many, whichlink_memory_tool_contractdeclares. Declare its kind and requirements inmodule.toml(Adding a memory engine). - Where Link Harness keeps conversations, a store driver (SQLite, a
database off the machine): a module of its own answering
contractandcallinlink_store_contract::store, checked withlink_store_contract::store::check(andcheck_jobs, for one that keeps a scheduler's jobs too). - Link's store drivers:
modules/agents/stores/sqlite-store(lnk-sqlite-store), declared as a store module. An agent's spec names it ([storage] conversations).
The sandbox and its bridges
What one harness may do (its folders, ports, which permissions it has)
stays in modules/agents/agent. Anything else that should run confined
writes a Spec, makes a Confinement from it (Confinement::of) and
calls link_sandbox_client::wrap.
What a sandbox can and can't reach
The Seatbelt and bubblewrap rules, permissions, the probes (lnk sandbox check) and lnk sandbox run are modules/security/sandbox;
the rules themselves, per OS, are in its wall
modules/security/sandbox/confine (linux/, macos/). The policy and
permissions a caller passes are link_sandbox_client.
A bridge out of an agent's sandbox
A bridge is a program outside the sandbox doing one kind of thing for
the agent. It goes in the module that runs it, on the server every
bridge runs on (link_sandbox_bridge::serve), saying only what it does with a
call and within what limits; its tests run
link_sandbox_bridge::conformance::check against it, listening. What every
bridge is, who's calling, its proof, the error envelope, the server and
that test, is modules/security/sandbox/bridge (link-sandbox-bridge).
Measures, files and clouds
What's measured, the files sent to the user's clouds, and the cloud accounts and boxes:
- Measuring agents and this machine (
lnk measure: what's read from outside, the watcher, what it keeps, the export):modules/tooling/measure. The measures and how they cross programs, OTLP, arelink_measure_contract::client. What a harness counts itself, it appends toLNK_MEASURES(Link Harness,modules/agents/harnesses/link/, for its own). - Files to the user's clouds (
lnk storage):modules/storage/storage. The cloud adapter uses the connected account's credentials to copy files directly to its storage. - Connecting cloud accounts (
lnk cloud), and machines in them (lnk box):modules/cloud/cloudandmodules/compute/box. Neither knows which cloud, which is the adapter's job. A box is a machine runninglnk, and what runs on it belongs to the module that runs it locally. - Support for one cloud (AWS, Google Cloud, ...): a new module, an
owner-local member answering the adapter commands
link_cloud_contractdeclares. Declare its kind and requirements inmodule.toml, and the commands it implements inactions.toml(Adding a cloud).
Modules, commands and shared code
A new part, a new command, and what every module shares:
- A new part of Link (a new
lnkgroup): a new module, an owner-local member (Adding a module). - A new
lnkcommand: the module owning its group, declared in itsactions.tomlwith its help, and the shapes it takes intypes.toml(Add a command's flags). - What
lnk uninstallstops and deletes of a module: that module, answeringuninstall(link_core::uninstall). The core only asks. - Something every module needs:
core/framework, if it is small and truly shared. - How a secret is held (never printed, zeroed when dropped):
packages/secretive(Secret). A field holding a secret is aSecret, read withexpose()only where it's used. - Documentation website:
web/apps/docs, within its web workspace. It keeps nothing and reads only the repository's docs.
A call Link makes over HTTP
A call to a service, such as the account API, a cloud API, or a chat
service, goes through link_fetch::Client
(packages/fetch, link-fetch), the only place Link's own code builds
an HTTP client: the request a Serialize type, the answer a
Deserialize one, its credential a Secret, and what differs a named
rule of the client's (Link's own calls).
What an agent fetches (a page, an MCP server) and a model's provider
don't go through it, and each such client is a reviewed exception.
Principles
What Link holds to in every part:
- Every engine is swappable behind a documented contract. A harness is
any
lnk-<name>answering the adapter commands, so closed code stays in its own repository, and Link never names it. - Link owns what stays the same when the harness changes. That is settings, the files folder, the connections, switching, and which machine runs it. A harness that speaks a connection keeps speaking it, and for one that speaks none, Link carries the messages.
- Work runs where it belongs. A box routes, a model cloud thinks, a bucket remembers, a scheduler wakes. Nothing that belongs elsewhere runs on the box.
- Link's harness runs no code. Tools are MCP servers outside it, sandboxed, in any language, and shared by every harness. Keys never reach it, because the proxy adds them.
- Turns hold no state between them. Any process on any machine can take the next turn.
- Conversations are append-only. They are an event log that is never rewritten, and the prompt is sent the same way so the provider's cache holds. There is one layout on disk and in a bucket, in plain files a person can read, behind a storage seam. Tokens are always recorded, and cost only from a real rate.
- Build the seams, not the implementations. An interface has one implementation, and the others aren't built until something needs them.
- Written for the densest deployment, run at the safest. Code is written as if many agents share one process, with the agent always an argument, every path from one function, and a test that one agent can't reach another's. It runs one process per agent.