Interface
A harness program, lnk-<name>, answers a set of commands and speaks
typed conversations. This page lists both.
Harness programs (lnk-<name>)
lnk-harness and every harness adapter from outside Local Link answer
these commands. The contract's source is
harness.rs,
and the authenticated storage and context protocol is in
Portable context. What every harness shares apart from
how Link runs it is in Harness Base,
the words its messages and skills are written in are in Harness
Wire, and the
Conformance Kit
checks a harness program answers all of it.
Command Declarations
The protocol's commands are declared once, in the contract crate's
actions.toml, with what each answers
in its types.toml. state on its own is
the state group's default, beside state export, state schedules
and state clear-schedules. Each harness program lists the commands it answers
under [implements] in its own actions.toml, and its command line is
generated from that, so every program reads a command the same way.
Commands a Program Extends
A harness program that takes more than the protocol's shape declares that command
as its own: Link Harness's serve, with --agents and --control, and
Hermes's state clear-schedules, with the context its exported
schedules name. Settings and portable state remain typed requests on
standard input. Extra arguments are refused before those requests are
read.
Versions
The contract has a version, the harness protocol's, which
harness/protocol.toml declares (link_harness_contract::harness::PROTOCOL,
now 2) and a change to it advances. An agent refuses to start a harness
whose adapter states an unsupported version, including zero, by name, naming
lnk upgrade.
Over the Agent Client Protocol
The Agent Protocol brings the Agent Client Protocol (ACP) and Link's Agent State Protocol (ASP) together. ACP provides sessions, prompts, streaming, cancellation, and capability discovery. ASP adds optional portable-state exchange and turn steering. This adapter interface supplies installation, launch, and native-state operations around those protocols.
Where each command runs
install, configure, command and health run inside the sandbox,
unless it's off; traces, written, clean, connections, state, internet-hosts, needs,
endpoint and contract run outside it. Informational commands print
replies; clean edits only the selected migration copy.
Their environment
The four inside the sandbox run with HOME set to the harness's home,
TMPDIR its tmp/, LNK_FILES the files folder, the agent's Home,
and LNK_AGENT_FOLDER the agent's own folder (agent/, its collections
kept at file). LNK_AGENT is the agent's name, LNK_AGENT_ID its ID
and LNK_OWNER its owner (acct-<id>, or <user>@<machine> before you
sign in).
The agent's ports
LNK_PORT is the agent's base port, set for every agent, main too,
since another user's agent may hold the adapter's default. Its ports go
from there, within as many as its
contract's ports and one more, or 200 when it doesn't say, and
Launch.ports outside that are refused.
Its own measures
LNK_MEASURES is a file in its home where the harness may append its
own measures, a line of OTLP JSON at a time, holding the file's lock
(flock, LOCK_EX) as it writes (link_measure_contract::client::append):
what it counts itself, a turn's tokens, cost, calls and times. The rest
is dropped as lnk measure reads it, and the file emptied, holding the
lock, once every line is read.
Asked once
contract, connections, internet-hosts, endpoint (for each base port) and
needs (for each input) are asked once a process while the adapter's
program stays the same file, and again once it's replaced or rewritten.
Set it up and run it
The commands lnk-agent asks to install the harness, configure it, run
it and check it answers, each assumed as it says when an adapter
doesn't answer it.
lnk-<name> contract
What the adapter speaks and its harness takes, asked once a process: the contract's version and each of its parts, on Harness Contract.
lnk-<name> install
Installs the harness with its own installer, or does nothing, and asks
nothing. It says so first when it installs, and shows progress: its
installer's own output, and every 30 seconds beside it a line
saying it's still installing and for how long (the contract's
progress::Heartbeat, its period in progress.toml), so neither a
person nor a program watching its output takes a long download for a hang.
lnk-<name> configure
Writes the harness's own config from the agent's settings:
Settings. lnk-<name> needs, beside it, says what the
harness needs beyond Link's defaults (Settings).
lnk-<name> command
Prints Launch as JSON, how to run it in the foreground: {"argv", "env", "write", "read", "ports", "serve"?, "services", "wait_secs"?}.
lnk-agent refuses one that would widen the sandbox.
serve
Of ports, those Link reaches from outside the sandbox (its gateway or
endpoint, its health check), the only ones served on this machine's
loopback behind its proxy. Left out, all of ports.
wait_secs
How long the harness may take to answer health after it starts, at
most 600. Left out, 60 seconds (Launch::wait).
lnk-<name> health
Exits 0 when the running harness answers, reaching it on its ports on
this machine's loopback, the only network it has in the sandbox. Read
by lnk agent start, and by lnk agent show when nothing on its
saved ports answers a request with success, a 2xx. What does is the
harness, up, its proxy closing without an answer; any other answer,
such as a 503, is the health check's to judge.
lnk-<name> internet-hosts
A JSON list of the hosts its install and configure reach, as lnk agent permission add --internet.hosts takes them (["registry.npmjs.org", "*.githubusercontent.com"]). With the sandbox and [internet], every
step runs behind a proxy of its own, direct, and those two reach only
these hosts; an adapter without the command lets them reach any host on
the internet.
What the other steps reach
link reaches what the agent may while it runs (lnk agent permission add --internet.hosts, --internet.tcp; "*": any host), and health only the
harness's ports on this machine's loopback.
What it says of its harness
The commands that say what the harness speaks, where it's reached, what
it keeps and where it writes, each read by the lnk agent command
named.
lnk-<name> connections
A JSON list of the connections its harness speaks, by their modules'
names (["telegram", "slack", "discord", "signal"]); an adapter
without it speaks Telegram. Read by lnk agent connect, which refuses
one the harness lacks, lnk agent harness set and lnk agent show.
lnk-<name> endpoint
For a harness that speaks no connection itself, where Link posts its messages: Harness Endpoint.
Conversations
lnk-<name> instructions [--json] prints the system prompt its harness
sends its model now, lnk-<name> conversation <thread> a conversation
as a person reads it, and lnk-<name> conversations move <way> moves
the agent's conversations to another way of keeping them:
Conversations.
lnk-<name> state
Prints link_harness_contract::harness::State as JSON: {"include", "exclude"}, paths ~/... in its home that hold the agent, and those
under them that are its install (programs, runtimes, logs, caches,
.env). Read by lnk agent state-send.
lnk-<name> link <connection> [--again]
For a linked connection (describe's linked: Signal), whose account
the harness links itself: links it in the home, its QR code on the
terminal, once configured. It exits 0 at once when it's linked
(--again: links it anew), and 10 (NOT_LINKED)
when it isn't and there's no terminal.
Read by lnk agent connect (--again), lnk agent start and use,
before starting the harness.
lnk-<name> traces
A JSON list of each place the harness writes when it isn't in its home,
and what kind of thing is there: {"kind": "home", "path": "~/.<name>"}, the path ~/... or absolute, {uid} for the user's id.
Read by lnk agent harness show, which labels each by its kind, and
lnk agent harness delete --harness <harness>.
Its kinds
A kind is home, config, secrets (a .env-style file of keys and
tokens), login (one of its own that can't move), service,
program, package (what its installer put beside it), cache, log,
lock, browser, agent or profile; any other entry is refused.
An install's agents
An agent path is one of several agents sharing the home: {agent} is
its name, {-agent} a dash and its name, and for the install's own
agent main and nothing (~/.openclaw/workspace{-agent}). A profile
path is another agent's whole home (~/.hermes/profiles/{agent}).
lnk agent migrate makes each an agent of Link's.
lnk-<name> written <home>
A JSON object naming the version that wrote the install whose home is
<home>, and why Link can't run that state when it can't:
{"version": "2026.9.6", "refused": null}. Read by lnk agent migrate,
which refuses a state with refused set before copying anything.
lnk-<name> clean <home>
Takes the secrets on its stdin, a JSON list of their values, out of the
files of its own in the home <home> keeps them in, other than its
secrets traces, which Link edits itself. An adapter whose contract
says forget answers it. lnk agent migrate runs it on its copy of an
install for each secret it takes, so the copy keeps none of them
before the agent's first start.
lnk-<name> uninstall --parts --json
As every module's (Module
Protocol),
run outside any home: the credentials its harness keeps in each agent's
home (link_harness_contract::harness::homes:
~/.lnk/data/agents/<agent>/harnesses/<name>), such as a token or a linked
device it made itself, as part agents's credentials, with no paths:
the folders are the harness module's. Read by lnk uninstall --parts
(lnk secret list).
Without it
An adapter without uninstall holds nothing lnk secret list shows, so
the list names no credential in its agents' homes.
Adapters from outside Link
Any lnk-<name> answering the commands above is a harness: lnk agent harness set <name> runs it like Link Harness. A harness Link doesn't write
lives in its own repository, and releases and signs itself.
Releasing
A GitHub release holds lnk-<name>-<target>.tar.gz for each target it
runs on (aarch64-apple-darwin, x86_64-apple-darwin,
x86_64-unknown-linux-musl, aarch64-unknown-linux-musl), each with
lnk-<name> alone. lnk on a machine whose target it lacks refuses it,
and so does a box of that processor. lnk-<name> --version prints
lnk-<name> <version>.
Its signature
The release holds a SHA256SUMS of its archives, signed with the
repository's own Ed25519 key (ssh-keygen -Y sign -n link-release -f <key> SHA256SUMS, giving SHA256SUMS.sig), and the key's public half
as release-key.pub.
Installing
lnk module add --url https://github.com/<owner>/<repo> takes the latest
release, shows the key and asks, then pins both
(Modules).
It asks the program only --link-describe, installing any module that
describes itself by its name but a standalone program.
Updates, lists and boxes
lnk upgrade takes each one's latest release, signed by the pinned
key, when it's newer. lnk agent harness set lists it with where it came from
(lnk module list --json), and lnk agent move adds it on the box from
the same repository, with the same key.
Without a release
A lnk-<name> you put on the PATH yourself works too, by name,
unsigned, and yours to update and put on a box.
The smallest one
The smallest adapter answers contract, command (its Launch),
health, needs and endpoint, and serves ACP at that address: Link carries Telegram for it, and the sandbox, the model's key
on the wire, moving and switching work as for any harness.
Shared Vocabulary
Harness Vocabulary connects the protocol-free base, thread, skill, and in-process runtime types used at these boundaries.
Implementation References
Harness Hub explains native process and session ownership. Harness Prompts defines the in-process runtime boundary, Runtime Comparisons describes controlled fixtures, and Decisions explains the contract’s state-transfer choices.