Switch harnesses, keep your agent

Change what runs your agent in one command, and back. Your agent keeps its model, files and connections, and Link installs the new harness for you.

Switch in one command

lnk agent harness list lists the harnesses and which one runs your agent, and lnk agent use --harness <harness> switches to one, installing it the first time.

lnk agent harness list  # list the harnesses and which one is active
lnk agent use --harness hermes    # switch to Hermes, installing it the first time
lnk agent use --harness link      # back to Link Harness

Compare Harnesses sets the four side by side to help you pick.

What comes along

Your agent keeps its model, key, files folder and connections. If the new harness doesn't speak one of your connections, use says so and that connection stays quiet until you switch back. Each harness's own state stays in its home, and a copy comes into your agent's folder.

Your conversations

Where both harnesses support session transfer, use asks the harness it leaves for its state over ASP, the Agent State Protocol, and keeps it in your agent's folder (harnesses/<name>.json). Once the new harness answers, it imports the conversations that went on elsewhere since it last ran, and each chat follows its thread there. A message that arrives meanwhile, typed or held by a channel during the switch, waits for them, at most five minutes, so it goes on in its conversation.

Non-text state

Switching compares full ACP updates, including tools, thinking and media. Link Harness and Hermes keep imported updates exactly for export, with separate native records for text, completed tool calls and supported media. Neither executes a historical tool call. Native thinking and stored media are included in their exports. Link Harness’s import describes its endpoint behavior.

Named omissions

Session support alone promises text. Before switching, use names the non-text content the destination cannot use and asks for agreement, or requires --yes in a script. Exact source updates stay in each harness's snapshot. Thinking without a destination's native signatures, audio and unsupported session metadata remain archival in Link Harness.

A round trip

Switching back finds the harness's own state in its home, with portable messages from elsewhere imported on top where supported. OpenClaw takes in no conversation from elsewhere: there, each chat starts afresh, and its conversations can be exported on the next switch.

Conversations that diverged

When the same thread continued separately in two harnesses, Link keeps both versions rather than merging their messages. The destination's keeps the thread's name, and the one brought in goes on a thread beside it named for the harness it came from, link:main~hermes. Both lnk agent chat list and lnk agent chat show reach it. Every harness that takes conversations in does the same, and use names each such thread. A conversation the destination already holds is not imported again, and one that only went on in the other harness goes on in the destination's thread.

A stopped harness

If the harness being left is not running, Link uses its last kept copy and says so. Changes since that copy are available only when the harness can export them; a switch cannot claim a fresh capture from a stopped process.

One running in a terminal

A switch while your agent runs in another terminal reads its harness's state first, then stops it there as lnk agent stop would. The new harness starts in the terminal that ran use, or as a service without --foreground.

Who your agent is

Who your agent is comes along both ways: its persona, owner, standing instructions and skills go into Hermes's and OpenClaw's own files at each start, and switching away from either, the persona, instructions and skills made there come into your agent's folder wherever it has none, and use says what came.

What stays behind

Before it switches, use lists what the new harness won't carry: the old one's conversations unless it gives them and the new one takes them in, so DeepSeek's, and every one going to OpenClaw; the old harness's own memory files, unless both carry who your agent is; its skills and persona, unless both harnesses read them from your agent's spec; and what your agent's spec turns on that the new harness doesn't do. Answer no and nothing changes; in a script, add --yes. What stays behind is there again when you switch back.

MCP servers you added to a harness

A switch carries the tools your agent's spec gives it, never the MCP servers you added to a harness's own settings. Once the old harness gives its state, use names each such server, which stays with that harness. Add one to your agent's spec to use it on every harness.

A switch that fails

A switch that fails once the old harness has stopped starts your agent again on it, so it answers where it did.

What it asks for

A harness that needs more than Link's defaults asks before your agent switches. It might want the network without its filtering proxy, for example, and it says what and why. Answer no and nothing changes. What it asks, and how to take it back, is in Permissions.

Bring an agent you already have

An agent you run with OpenClaw, Hermes or DeepSeek, installed outside Link, comes under Link with its harness:

lnk agent migrate                    # find it, say the plan, then do it
lnk agent migrate --harness hermes   # when more than one is installed

Its plan

Before anything happens, migrate says what it found and where each part goes: its own background service stopped and kept from starting (two would answer one bot), its home copied into the agent's harness home, its secrets handed over, and what stays where it is. Then it says each step as it ends.

Its variables

The plan lists every variable of its .env in a table: what Link makes of it, and where it's sent. Check each goes where you expect, as a variable may be used other than its name says. Link knows the variables in variables.toml, and takes none of them plain.

What each becomes

A hosted model's key becomes the agent's model key, kept as lnk agent start keeps one, and its proxy adds it for its provider. A service's key Link knows is given to the agent sealed for its API's one host. A bot's token goes to its channel. Any other secret is left in the original, and the plan names the lnk secret add that gives it sealed.

Sent elsewhere

A key is left in the original, and said, when a variable beside it sends it elsewhere: an OPENAI_API_KEY with OPENAI_BASE_URL naming another provider's API goes there, not to OpenAI. Every secret is taken out of the copy's .env, so the harness never holds its value.

Its version

A state written by a newer harness than the one Link runs is refused before anything is copied, naming the version and why: OpenClaw's meta.lastTouchedVersion in openclaw.json, Hermes's _config_version in config.yaml. Updating Link first lets it through.

Several agents

Every OpenClaw agent folder (~/.openclaw/agents/<name>, with its workspace-<name>) and every Hermes profile (~/.hermes/profiles/<name>) becomes an agent of Link's of the same name, each named in the plan and asked about, so any can be left out. Each gets its own copy, holding no other agent's folders, and each takes the install's model key as its own.

A bot's token

A bot's token (Telegram, Discord, Slack) goes to Link's connection instead: in a terminal, migrate ends by connecting it with the token given, so you only confirm the bot is yours.

Its paths and its sandbox

Every path into the harness's home, in its settings, its sessions and any text file of the home, is rewritten to its home under Link. A database is copied whole by SQLite, its write-ahead log in the copy, and its paths are rewritten through SQL, never as text. migrate says what the sandbox changes: the install reached your whole computer, and under Link it writes only its home and your agent's files. A login of the harness's own that can't move, such as Hermes's auth.json, keeps working (migration decisions).

The original

The original keeps working until you remove it: its files are copied, never moved. Its service file is kept in ~/.lnk/kept-off, by its path in your home folder, and put back when you remove the agent. A home that is a link to a folder elsewhere, as a dotfiles repository keeps one, is copied from that folder.

Stopped partway, and after

Stopped partway, lnk agent migrate again carries on from the step it stopped at, and lnk agent delete <name> undoes what it did and puts the service back. After a finished migration, lnk agent delete turns the original's service back on too, so it runs as it did. In a terminal, it ends by offering to start the agent under Link, its harness installed in its home. Once the agent answers under Link, lnk agent -a <name> use link switches it to Link Harness whenever you like.

Use another harness

Five harnesses besides Link Harness come with Link, and lnk agent use installs each the first time. Each downloads a runtime of its own, so the first time it asks, saying what it downloads; in a script, add --yes.

lnk agent use --harness openclaw    # installs OpenClaw, then starts it
lnk agent use --harness hermes
lnk agent use --harness deepseek
lnk agent use --harness claude
lnk agent use --harness codex

Harness	What it is
OpenClaw	The personal AI assistant, from openclaw.ai
Hermes Agent	Nous Research's agent
DeepSeek Harness	DeepSeek's open-source agent, `dsh` (GitHub)
Claude Code	Anthropic's coding agent, over its ACP adapter
Codex	OpenAI's coding agent, over its ACP adapter

Each page says how its harness runs, its limits, and what to do when it doesn't answer. lnk upgrade keeps all six up to date with Link.

A harness from outside Link

Any other harness comes from outside Link, as a plugin from its own repository, signed by its own key, that answers the harness contract. Add it once, then switch to it by its name (Plugins).

lnk plugin add --url https://github.com/example/lnk-example   # shows its key and asks

Remove a harness

Delete a harness you no longer use, after show has told you what it holds.

lnk agent harness show --harness openclaw   # its home, and anything of it left elsewhere
lnk agent harness delete --harness openclaw           # delete all of it

remove deletes the harness's install, settings, memory and conversations, and whatever show finds of it outside its home. It deletes its grants too, unless another agent here runs it, so added again it asks again for what it needs. Your files folder and your agent's settings stay. When a switch goes wrong: Troubleshooting.