Agents of your own, a text away

The first start

The first start installs the harness and asks which model your agent thinks with, which folder it works in, and which of Link's tools it gets: Memory, picked unless you say otherwise, Web, whose search asks for a Brave Search or Tavily key, Browser, which needs Chromium or Google Chrome on this computer, and Desktop, which needs Linux's Xvfb. Later starts reuse what you chose.

A personal agent

A new agent is a personal agent: scheduler, run, file and code are off until you add each one with lnk agent tool add <name> or enable it in your spec. Add reusable task instructions through Skills.

Create on a hosting account

lnk agent create work --on <account> makes a blank agent directly on an account that hosts agents, using its harness and model defaults. It asks for no model key and makes no local copy. lnk agent list shows it there; lnk agent connect telegram --agent work connects it through that account. A box name after --on still creates the agent on the box.

Its tools, asked once

The tools are asked once per agent, whatever you answer, and lnk agent tool add <tool> adds one later. Picking Memory offers its embedding model too; without it, memory searches by words only.

Without a terminal

Without a terminal to ask in, its folder is ~/Link/Agents/<name>/Home (--files <dir> picks another), and it says so and names the command for its tools, and a later start in a terminal asks.

The models it offers

In order: a model already running on this computer, which is free and private; with none, on an Apple Silicon Mac, one to install, a few GB; then an API key from Anthropic, OpenAI or OpenRouter.

What every start shows

Every start ends with the table lnk agent status shows: whether it runs, its model, its tools, where you text it, and where its files are. Running means its harness answers; a key the provider refuses shows at your first message.

A hosted model's key

Give a hosted model's key when lnk asks for it, or as the provider's variable, as above: never on the command line, which other users of this machine can see. To change the model later, see Switch Models. Your agent answers only while its machine is on.

Talk to it here

Talk to your agent in this terminal, or from a script, with no account or bot.

lnk agent chat start                   # a conversation in this terminal
lnk agent chat send -m "hello there"   # one message and its answer, for a script
lnk agent chat start --chat work       # select the named conversation, link:work
lnk agent chat show link:main  # the conversation, as you would read it
# the message on stdin, the answer as JSON
echo "hello" | lnk agent chat send --json

Give it tools

Add Link's tools to your agent, or take them away, one at a time.

lnk agent tool list           # each of the tools of Link: whether it has it, and what it needs
lnk agent tool add memory     # search over its files and conversations, and notes it keeps
lnk agent tool add web        # pages, and a search with a Brave Search or Tavily key
lnk agent tool add browser    # a browser of its own: pages opened, clicked, typed into and seen
lnk agent tool add desktop    # a desktop of its own, on Linux, where the programs it runs show
lnk agent tool add file       # enable file reads and writes within its sandbox grants
lnk agent tool add scheduler  # enable subagents and scheduled work
lnk agent tool remove web

State is on when the tool is configured for this agent, and off otherwise. An installed plugin alone does not enable its tool. Scheduler, run, file and code start off in every profile. add and remove save their [behavior.tool.<name>] enabled switch in Config/agent.toml, preserving other opinions and comments. You can also set that switch yourself. Grant the folders or programs each tool needs in its sandbox file; only confirming a proposal widens those grants. A request outside them is refused by the tool; saved memory uses its separate notes permission.

--live

--live prints a line a step: a message come, the model thinking, and each minute it goes on that it still is, a tool called and answered or failed, the answer with how long it took and its tokens, and the agent stopping or starting. A slow answer then shows where it waits: on the model, on a tool, or on nothing. It reads Link Harness's conversations, so with another harness it shows only starts and stops.

status

status exits nonzero unless the agent answers. When its proxy has paused its wire, or every wire is stopped, it says so and why. On a box, where no notification shows, that's where you see it. For other programs, status --json and list --json are in contracts.

The harness's prompt

Link Harness shows the prompt it assembles from the agent's instruction files, tool descriptions, skills and notes. Link Harness explains its section order, caching and editable sources. A harness from outside Link builds its own prompt, which this command cannot show.

Read its conversations

Read a chat as you would, or move the old ones to the way its spec keeps them now. Only Link Harness prints and moves its conversations: on another harness, these commands are refused and name lnk agent use --harness link.

lnk agent chat show telegram:123456789   # one chat, as you would read it
lnk agent chat show link:main            # what you said with lnk agent chat send
lnk agent chat convert                # each chat kept the way its spec says now

Link Harness keeps each chat in its files, as a log you can cat, or smaller, or in a database: its spec's [storage] conversations says which, for a new chat (how). lnk agent chat show prints a chat however it's kept; move, with the agent stopped, moves the old ones to the way the spec says now.

Messages between them

On Link Harness a member sends another a message with its scheduler, and the answer comes back as a message from that agent, never from you. The scheduler's caps stop two that keep answering each other. You talk to each member on its own connections.

Its folder

The team's folder is ~/Link/Teams/<team>/Shared, and each member reaches only what it's granted of it, and no other team's.

Its memory

The team also brings a memory over that folder, one server for the members granted all of it (.), on Link Memory: when that isn't on the machine, a member's start says so before installing it, and asks first in a terminal.

Its file

Its file, ~/.lnk/teams/<team>.toml, holds the members and the opinions they share, and each change restarts the members that run.

Invite an agent from another account

On a cloud that hosts teams across accounts, both owners agree:

lnk agent team invite design --cloud my-cloud --agent acct-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/k3m4n5p6q7r8 --as reviewer --read . --write notes
lnk agent team join design --owner acct-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --cloud my-cloud --agent reviewer
lnk agent team leave design --owner acct-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --cloud my-cloud --agent reviewer
lnk agent team remove design --cloud my-cloud --agent reviewer

In a terminal

One started with --foreground is running in a terminal to status, and stops with Ctrl-C there, lnk agent stop, or a SIGTERM or SIGHUP to lnk, which it passes on to the harness and waits for (one asleep for being idle just ends). On Linux, lnk killed outright (SIGKILL) sends its harness a SIGTERM all the same, so nothing it started keeps the agent's ports. Until then another lnk agent start says it runs there. Its output shows there and goes to its log too, as a service's does, so lnk agent logs reads it either way.

What a stop ends

A stop ends everything started for the agent, however it runs (in a terminal, as a background service, or woken when a message comes): its harness, its bridge and connections, its scheduler's runner and the calendar's wake, and its background commands. Nothing of it fires a job or answers a message until it starts again.

What goes

remove stops the agent and deletes its settings, its harnesses with their installs, memory and conversations, its log, its keys, its sandbox rules and its memory's and scheduler's tools.

Its files

Its files (its Home and its own folder, with its instructions, skills, conversations, memory's index and scheduled jobs) go only if you say so; kept, they're moved to ~/Link/History/Agents/<name>-<date> for 30 days, and a Home you chose yourself stays where it is. Its buckets stay in your clouds, so lnk agent restore work brings it back, asking for their password.

What stays

What lnk measure recorded of it stays until it ages out. It leaves every team it was on, and the teammates that run restart to take that. With one agent left, commands act on it without --agent.