Get Started

How Link's code is laid out, what may depend on what, and where new code goes. Why it's built this way: Philosophy and Decisions.

The core and its plugins

The core architectural decision: lnk is a small core, and everything Link does is a plugin, the way git runs git-<name>. It is also the first thing a user meets: install.sh installs the core alone, and lnk up asks which plugins to add (docs/en/plugins).

• A plugin is its own program, lnk-<name>, next to lnk; lnk <group> ... runs it. What a user installs is exactly what runs, and one plugin can't break another.
• The core only installs, runs, updates and removes plugins. New behavior goes in a plugin, never the core.
• Plugins use each other only by running lnk <command> and reading a documented output (docs/en/dev/contracts.md), never by linking each other's code or reading each other's files.
• Each of Link's plugins ships as its own signed archive, at the core's version, and so do Link Harness, Link's tools (Link Memory) and the OpenClaw, Hermes and DeepSeek Harness adapters, built from their own repositories; a harness from outside Link ships from its own repository, signed by its own key.
• Code goes in the plugin whose purpose it serves, and a plugin's purpose is its name. Before adding code to a plugin, ask: would I still use this code without installing the plugin it serves? Does this plugin have to know another's files, API or quirks? If either is yes, it goes in the plugin it serves, or in a plugin of its own when several need it and none owns it (the login is accounts, not the tunnel's, because boxes need it too). The same holds for link-plugin and the core. The test worked through: "Where code goes: the seam test" in docs/en/dev/plugins.md.

Layout

docs/ (the docs of the core and its plugins, in English in docs/en/; the website, link-web beside this folder, renders them) and src/ (a Cargo workspace, Cargo.toml at the root), organized by where the code runs:

Dependency rules

src/tests/e2e/tests/architecture.rs enforces these:

• link-protocol and link-plugin depend on no other link-* crate.
• link-relay and link-agent depend only on link-protocol. The server and the local machine never depend on each other.
• Plugins (link-plugin-*) depend only on link-plugin and link-agent. They never depend on each other: one uses another by running lnk <command> (link_plugin::lnk()) and reading a documented output, such as lnk model serve --json.
• link-cli (the core) depends only on link-plugin; it runs plugins as programs and links none of them.
• Demos depend on no link-* crate.
• The mini harness and the conformance kit depend only on link-plugin.

A new crate goes in members of the root Cargo.toml, and in its [workspace.dependencies] when another crate depends on it, and in allowed() in architecture.rs if it is a new kind.

Where does new code go?

Prefer a new plugin over growing the core or another plugin. Keep crates small and names literal. Adding a plugin: "Adding a plugin" in docs/en/dev/plugins.md.

Changing the protocol

Relays and installed CLIs upgrade at different times, so old peers must keep working. Prefer additive #[serde(default)] fields (no version bump). Anything breaking bumps link_protocol::VERSION, and the relay keeps serving agents down to MIN_AGENT_VERSION. New behavior is negotiated in Hello/Welcome, like flow_control. Details and tests: docs/en/dev/protocol.md.

Principles

• 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: settings, the files folder, the channels, switching, and which machine runs it. A harness that speaks a channel keeps speaking it; 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: the proxy adds them.
• Turns hold no state between them. Any process on any machine can take the next turn.
• Conversations are append-only. An event log, never rewritten, and the prompt sent the same way so the provider's cache holds. 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 with one implementation; 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 (the agent always an argument, every path from one function, a test that one agent can't reach another's), and runs one process per agent.