Agent Files

Find your agent's saved files and Link's private runtime state, grouped by purpose. Configuration explains which files control its behavior.

lnk agent show

Settings and grants

What you chose for the agent, what you granted it and its harness, and what a start remembers of the last one. ~/.lnk/safe/agents/<name>/ (700) holds its log, its foreground lock and its proxy's sockets.

~/Link/Safe/Agents/<name>/agent.toml (600)

An agent's setup and [behavior] in one editable file (Configuration). Commands save choices here, and no agent sandbox reaches it. This machine's agent is main. A missing file is recreated with default configuration. It holds only what's the agent's own, so it can be carried to another machine or person whole: its ID, service, owner, ports and stopped services are this machine's records, in identity.toml and here.toml below, and a file naming one of them is refused.

Its Schema

Its first key is schema, the settings file's version, which every save writes, so a later release reads an older file through its steps. Its [behavior] names no schema of its own: it is the agent spec at the agent spec's current schema, and when that moves the settings file takes a step of its own.

~/Link/Safe/Agents/<name>/sandbox.toml (600)

What you grant the agent, whichever harness runs it (Configuration). Missing files are recreated with closed permissions. Permission loading stays closed independently of whether recreation succeeds.

This Machine's Records

What this machine keeps of an agent that isn't the agent's own, so none of it travels in an archive.

~/.lnk/safe/agents/<name>/identity.toml (600)

Who the agent is on this machine: its ID, agent:<id>, the service it acts as and its owner. The owner says its kind: before you sign in, the user running Link on this machine, owner = { kind = "machine-user", user = "dana", machine = "danas-mbp" }, and signed in, your account, owner = { kind = "account", id = "<account ID>" }, as lnk agent list --json prints it too. An agent without one is refused, and any command's --agent takes the ID as well as the name. Deleting agent.toml keeps it, so the recreated agent has the same identity. It holds no credentials and no sandbox reaches it.

~/.lnk/safe/agents/<name>/here.toml (600)

What this machine gave the agent: its block of ports (port, block), its webhooks' own port, and the services of an install it was brought in from that it keeps off (stopped_services), and the folders of the PATH of whoever last ran lnk agent start (path), where its run and code tools find its programs. Each machine gives its own, so none of it travels with the agent.

~/.lnk/safe/agents/ids.toml (600)

Every agent ID this computer reserved or took in, under live, and each one lnk agent delete retired, under retired. lnk agent create reserves an ID that is neither, and a moved agent arriving with a retired ID is refused, so an ID never names two agents (Stable IDs).

Services and Teams

services.toml beside it keeps the services agents act as alike, each minted with its agent under an ID of its own (An Agent's Service), and team-ids.toml teams' IDs, each a group's, group:<id>: lnk agent team create and a team's definition reserve one there, a team moved here is taken in, and lnk agent team delete retires it.

~/.lnk/safe/agents/harness-grants/<harness>.toml (600)

What a harness said it needs here and you allowed, for every agent that runs it (Configuration).

~/Link/Safe/Agents/defaults.toml (600)

The proxy upstream each new agent here starts with (lnk agent route --default).

~/.lnk/safe/agents/places/runs-agents.toml (600)

Whether each cloud account runs agents, as its adapter answered agent-runs once, with the kind and identity it was asked as: lnk agent list asks only those that do, and an account connected again as another is asked again.

~/.lnk/safe/agents/places/cloud-teams.toml (600)

Where each team a cloud running agents keeps is, by its ID, for a team an agent here arrived on: its owner, relay and folder service, as the machine running the move read them. A machine with no account to ask, such as a box, reaches the team through them. An account here that lists the team says it instead.

~/.lnk/safe/agents/<name>/ports.json

The harness's ports at its last start, which lnk agent show shows for the agent.

<harness home>/.lnk/data/harnesses/configured and the rest

A hash of the settings, versions and files the last configure left, so a start with nothing changed skips it; delete it to configure again. What else a harness from outside Link keeps in its home, its repository's README says.

Keys, bridges and sockets

How the agent's bridge reaches it and proves who calls, and what a shared bridge or harness keeps.

~/.lnk/safe/agents/<name>/way-in.sock (600)

The bridge's way in: messages for the agent from its schedules and subagents, each proved as the agent that hands it.

~/.lnk/safe/agents/credentials/<id>.json (600)

The keyring: each running agent's identity and its key for this start, which every bridge checks a call's proof against; removed at its stop.

<runtime>/lnk/agent/network/<id>/ (700)

url.secret (600) is the agent's proxy secret, in its tool and local model URLs, by the agent's ID. Each start makes it new, before its proxy and its harness's configuration are made, so an address a program read in an earlier start is refused. <harness> is sockets between the harness's network and its proxy; <harness>-<step> for a setup step's (install, configure, ...), and <harness>-health for the health check's relay to the harness's ports.

~/.lnk/safe/agents/<name>/bridge.json (600)

For a harness with an endpoint: its endpoint, key, proof, connections and storage plan. Made at each start and used by the agent bridge to carry the connections the harness delegates to Link.

~/.lnk/safe/agents/<name>/bridge.log

The log of the connections Link carries, written by the agent's bridge as it carries them.

~/.lnk/safe/agents/<name>/sleep.sock (600)

Where the bridge tells an agent started in a terminal to stop its program for being idle, or start it again ([run] idle_after).

~/.lnk/safe/agents/bridges/ (700)

The bridge every agent here shares where shared_bridge is on: whom it carries (agents/<id>.json, written at each start, removed at each stop), each time zone's scheduler runner's agents (runners/), the agents asleep for being idle (asleep/<id>), and bridges.log. Each record and runner's file names its schema (bridges/record.schema.toml, and the scheduler contract's listed.schema.toml).

~/.lnk/data/agents/shared-harnesses/<owner>/ (700)

The harness an owner's agents share where shared_harness is on, and its HOME: what each agent is served with (agents/<id>.json), the agents' file it's started with, configure.lock, held by a start while it configures and joins, and shared.log. Each record and the agents' file name their schema (shared/member.schema.toml, and the harness contract's harness/shared_agents.schema.toml).

~/.lnk/safe/agents/<name>/hooks-seen.json (600)

The id of each post its webhooks took, kept 30 days, so a repeat is refused. Written whole by the bridge, never through a link, naming its schema (pushed/seen.schema.toml).

Storage and context

The agent's storage bridges, and what a harness keeps of the context it was given.

The agent's storage bridge, for a harness that keeps Link's collections with a restricted folder layout: each call answered by the driver of the place its collection is kept at here (lnk-sqlite-store, lnk-storage), run outside the sandbox. Legacy adapters reach it directly.

~/.lnk/safe/agents/<name>/team-files.sock (600)

The agent's files bridge, for its teams whose folders an account hosting agents keeps: each call proved with the agent's key, held to its grants here, and handed to the folder's service with the agent's own token. Only file, outside the sandbox, reaches it.

~/.lnk/data/agents/memory/<owner>/bridges/<agent>/storage.sock

The same storage bridge, for the agent's memory: alone in its folder, which memory's sandbox reads and every agent's sandbox hides, its calls proved with the agent's key. Besides what the agent's sandbox writes, it changes only its memory collection and, where its notes are written, memory/notes.md.

<harness's home>/.lnk/data/agents/context/binding.json (600)

A host-supplied native-hook binding: its storage socket and adapter name. A host that supplies one regenerates it for each binding and excludes it from move state; an adapter has no storage opt-in.

<harness's home>/.lnk/data/agents/context/ (700)

Adapter-owned finite cursors, native-memory export digests/versions and a serialized hook-client lock. Retained across restart and declared by native adapters as state.

captures/

It keeps private pending record batches until storage confirms them, at most 1,024 batches and 64 MiB.

<harness's home>/.lnk/data/agents/context/client

A sandbox-local copy of the adapter executable used by native hooks. Regenerated by configure.

<host-selected protected directory>/session-authority.json (600)

The explicit host-only session Ledger: versioned session mappings and active attempt/generation, at most 1 MiB. The interaction engine owns questions and approval decisions separately. Its directory is private (700) and outside runtime mounts. No command or adapter creates it by default (Portable context).

~/.lnk/data/agents/<name>/harnesses/link/config.json (600)

Link Harness's model and endpoint key, read at each message; written at each start.

Memory and tools

What Link's tools keep for an agent, and what its background commands and answers leave.

~/.lnk/data/agents/memory/<owner>/ (700)

The memory service an owner's agents on this machine share. Trusted records (agents/<id>.json), generation caches and service.log stay outside its sandbox. Its HOME and socket are in run/, which the engine may write. The generated agents-<generation>.json handoff and the storage sockets in bridges/ are read-only grants. The engine cannot change its next start's records or redirect the service log.

generation.json

The generation those records make, with each record file's inode, time and size, so a session reads it alone while they're unchanged. It and each record name their schema (memory/recording/seen.schema.toml, memory/recording/record.schema.toml).

A bound embedding endpoint

Shared memory's bound embedding endpoint is unix:<path> when supplied as --embed-url. Each request proves the current agent binding; the receiver resolves its owner from that proof and its Unix peer. A bound endpoint over HTTP is refused (embedding credentials).

~/.lnk/safe/sandboxes/tools/memory-<id>.json (600)

Its memory, as a tool (lnk agent memory start), by the agent's ID. Defined again at a start only when something it's made from changed.

~/.lnk/safe/agents/<name>/memory.json

What the memory tool was last defined from, so a start with nothing changed leaves it as it is. It names its schema ("schema": 2, memory/defining/record.schema.toml) and the final registered command's fingerprint. A missing fingerprint establishes no managed read authority.

~/.lnk/safe/agents/<name>/run.json, file.json, code.json and scheduler.json (600)

What its run, file, code, browser, desktop and scheduler tools were last defined from, there while each is defined: the tool's command line, when its program last changed and the Link that defined it, each naming its schema (defined/tool.schema.toml).

~/.lnk/safe/agents/<name>/scheduler-cron.json (600)

How to take away the calendar entry waking its scheduler, when its spec says driver = "cron": {"schema": 1, "remove": [...]}, the command lnk agent stop runs.

Its Runtime Folders

What it keeps while it runs that isn't its state, each a folder of ~/.lnk/data/agents/<name>/, out of every archive.

~/.lnk/data/agents/<name>/run/

Its background commands' records (600), written by run and each one's supervisor, swept by its bridge; each kept [tool.run] background_keep once it ended and was told. started says when each of the last day's started (background_per_day). They're runtime, not the agent's state, so they're kept here rather than under ~/Link.

~/.lnk/data/agents/<name>/caches/

Its programs' package caches: cargo's (CARGO_HOME), npm's, go's, Gradle's and what keeps to XDG_CACHE_HOME (pip's, uv's), each a folder of it, set by its run tool in each command's sandbox. They're its own, so a package it downloads never reaches what you build outside it.

~/.lnk/data/agents/<name>/browser/ and desktop/

The browser tool's profile, with the agent's sign-ins, and the desktop tool's display number and cookie (display, auth). They're runtime and credentials, never the agent's state, so they're kept here rather than under ~/Link. No harness reaches the profile. The cookie is read by every run call's sandbox, beside the display's socket, so the programs the agent runs can draw on its desktop.

<files folder>/background/<id>.out

A background command's output, both streams as one, its last [tool.run] background_output kept; read by the agent, written only by its supervisor.

~/.lnk/safe/agents/<name>/owed/ (700)

Where an answer to a message from others goes (its chat, another conversation, or nowhere), kept by the bridge until it went, so an answer finished after a crash goes there too; a subagent's conversation's is kept for its own subagents' answers. Each file names its schema (bridge/way_in/owed.schema.toml).

~/.lnk/safe/agents/<name>/received/<id>.json (700, 600)

How many messages each teammate (by its ID) sent the agent today (UTC), one file each: the bridge takes no more from one a day than the agent's own [tool.scheduler] per_day, and a message the harness never took counts nothing. Each file names its schema (bridge/way_in/received.schema.toml).

Teams

What Link keeps for a team, and for its memory.

~/Link/Safe/Teams/<team>.toml (600)

A team's file: its members, the folder they share, and the opinions they share (Team Spec), written by lnk agent team.

~/.lnk/data/teams/<team>.json (600)

What the team's memory tool was last defined from, there while it's defined: while it's there, the team's memory is the tool team-<team id>-memory, and without it the team has none.

~/Link/Teams/<team>/ (700)

What Link keeps for a team: its shared folder (shared) and its memory's index (memory/<engine>).

Moves

What a move leaves behind, holds on its way, and copies aside.

~/.lnk/safe/agents/transfers/moved/<id>.toml (600)

A note left when an agent moved away: where to ([to] name, and cloud = true for a cloud account that runs it, whose Home lnk storage push and pull then reach, as lnk agent list --json --here says), and when. A note a newer release wrote is refused, naming lnk upgrade, never taken for none, so a rollback never forgets where an agent went. The move journal beside it, ~/.lnk/safe/agents/transfers/moving/<id>.toml, is refused the same way, so a move under way is never forgotten.

~/.lnk/data/agents/move/<name>-<date> (700)

A moved agent's own folder and its Home, when it's its own, as agent/ and home/, kept 30 days, or as ~/.lnk/safe/agents/policy.toml's keep_moved says, so it comes back whole if it returns. It's kept apart from ~/Link/Archive, which is the archive's. A deleted agent whose files can't be one archive is kept here too.

~/Link/Archive/<name>-<date>.tar.gz (600)

A deleted agent's state, its settings, sandbox file and files, as one archive whose archive.toml records its deletion, kept as long as ~/.lnk/data/agents/move/. An archive you exported or put there yourself never expires.

~/.lnk/data/agents/harness-history/<name>-<date> (700)

The harness homes of an agent whose move wasn't seen running where it went, without the keys a harness keeps in them (its .env), kept as long as ~/.lnk/data/agents/move/. Its harnesses wrote them, so they're data, never in a Safe.

~/.lnk/safe/agents/transfers/receiving/<id>/ (700)

An arriving agent's copy and switch, by its ID, with move.json (its move, and when its copy came), before it's put in place; removed then, when its switch fails, or 7 days after a copy no switch came for.

~/.lnk/safe/agents/transfers/sending/ (700)

Where a move copies a file over 8 MB, or memory's index, aside, unnamed, to hash and send it as it was hashed.

~/.lnk/safe/agents/<name>/paused

The agent is paused for a move's switch: what carries its connections takes no message; paused.quiet beside it, once it stopped. A start removes both.

~/.lnk/safe/agents/places/.spool/ (700)

Where a hosted Home's push or pull (lnk storage push and pull) copies a large file aside to hash it, and unpacks a pull before it's put in place.