Where Link Keeps Things

Link keeps what's yours in ~/Link and what it needs in ~/.lnk, each thing in the folder of whatever owns it. This page follows a secret and an agent through those folders, from the day they're made to the day they're deleted, then lists every location.

lnk folder list

Two Folders

The two primary locations are in your home folder. Operating-system registrations and system installations use the additional locations listed below, with each component's own records identifying what it owns.

~/Link is what you see and work in. It holds your files, your agents' files and your teams' shared folders. Its Safe/ holds what you edit that steers Link, such as each agent's settings and grants. This visible folder is intended for people to find, understand and manage, whether they are programmers or not.

~/.lnk is what Link keeps. Its safe/ holds what Link writes that steers it, such as credentials, approvals and journals. Its exec/ holds the programs Link installs, and its data/ holds the rest, such as the homes of your agents' harnesses. Link manages these files, while developers and administrators can inspect them. This folder can contain important records and credentials; it is not just disposable cache.

Removal Is an Installation Responsibility

Link is responsible for clean removal of the software it installs, including third-party harnesses. Saved user data is an explicit choice. This guide is also a manual verification reference: after stopping the programs and removing their registrations, you should be able to check each declared location without relying on the uninstaller. The location map records moved folders, so checking default paths alone is insufficient.

Safe, Exec and Data

Each folder is one of three kinds:

  • Control steers Link: a setting, spec, preset, grant, credential, approval or saved yes. Control lives only in a Safe, ~/Link/Safe or ~/.lnk/safe, and no sandboxed run reaches a Safe by any path, for reading or writing.
  • Exec is what a run may execute: lnk, its modules and the harnesses Link installs, in ~/.lnk/exec. Every run can only read it. ~/.lnk/exec/bin holds only what goes on your PATH, lnk and its modules.
  • Data is everything else, what a run may be granted. Link never reads control from it.

A sandbox (the walls Link puts around a program it runs) hides both Safes whole and never lets a run write exec, so no agent can widen its own access or plant a program another runs. Safe means that sandboxed agents cannot read or write the folder. It protects the information that steers execution, including settings that are not secret.

One Folder per Owner

Each kind of thing has one folder in each part of the layout, named by its plural word. A folder directly in ~/Link, or in ~/Link/Safe, which mirrors it, is Title Case (~/Link/Agents, ~/Link/Safe/Agents, ~/Link/Safe/Models). Every folder below those is lowercase, as every folder in ~/.lnk is: ~/Link/Agents/main/home, ~/Link/Safe/Sandboxes/presets. An agent main has four folders at the same path in each part:

~/Link/Agents/main/
~/Link/Safe/Agents/main/
~/.lnk/safe/agents/main/
~/.lnk/data/agents/main/

The owner stays recognizable across these boundaries. Each part keeps the files appropriate to its purpose; parity of organization does not mean copying the same files into every folder. Commands stay singular, as in lnk agent. Link's own files sit at each part's root, such as ~/Link/Safe/settings.toml and ~/.lnk/safe/machine.toml. A name Link keeps in an owner's folder for itself can't name one of its things: an agent can't be named journal, since ~/.lnk/safe/agents/journal is the agent module's.

State and Prerequisites

A thing's state is its configuration and files: what you'd lose with the machine, and what someone else needs to have the same thing. What it needs to run, such as an installed harness, a credential or an approval, is a prerequisite, which each machine sets up for itself. State is kept under ~/Link, and prerequisites in ~/.lnk, so an archive carries a thing's state by copying its folders under ~/Link and nothing else.

Kinds and State Parts

Each owner in layout.toml's [owners] names its kind, the word for one of its things, and its state, the parts whose folder of a thing is state:

# layout.toml
agents = { module = "agent", kind = "agent", parts = ["link", "link-safe", "safe", "data", "exec", "archive"], state = ["link", "link-safe"] }

The layout refuses state in ~/.lnk, and a kind two owners share. A test holds the rest: every owner's folder under ~/Link is its state, and no program or credential is kept there. It lists by name the exceptions still left, a team's settings file in Safe/Teams and a box's spec in ~/.lnk/safe/boxes, until those kinds keep one folder per thing.

Operating-System Locations

These locations supplement the two home folders. System services use them only when those features are installed; the service contract describes registration and shutdown. Inspect Link-owned entries and their declared targets, rather than treating a shared operating-system folder as belonging entirely to Link.

/etc/lnk/

System configuration includes machine-kind information, service settings and worker configuration. This is protected control information, separate from the current user's Safe.

/usr/local/lib/lnk/

System-installed executables, including the secret keeper and sandbox worker's programs, live here. The system layout in layout.toml names the programs and their locations.

macOS

macOS uses launchd for background services and the login Keychain for secrets. User and system registrations are separate, and system state has a separate root from the two folders in your home.

~/Library/LaunchAgents/

Per-user service registrations are plist files named by each service's launchd label. Their program paths identify the executables they start; removing a file alone does not stop an already loaded service.

/Library/LaunchDaemons/

System service registrations use this directory. Their lifecycle is owned by the system service definition, and removing them requires the corresponding system permissions.

/var/db/lnk/

This is Link's macOS system-state root. It can contain protected worker records and system-service data, as declared by the system layout.

Login Keychain

Link-managed secrets use Keychain items under the service name link; the Keychain package owns their format. Inspect the relevant items, rather than deleting the Keychain file. A harness adapter's declared traces identify any additional login material belonging to that harness.

Linux

Linux separates user services from system services and keeps system state under /var/lib. The configured service backend determines which registrations exist; prepared guests can use a process supervisor instead.

~/.config/systemd/user/

User service units live here by default, or under $XDG_CONFIG_HOME/systemd/user/ when that variable is set. The service records identify the unit names; stop and unregister those units before checking that their files are gone.

/etc/systemd/system/

System service units are installed here by their declarations. This is a shared system directory: inspect only Link-owned units and the programs those units launch.

/var/lib/lnk/

Link's Linux system state includes the secret keeper's store in secret/ and declared worker records. Also check /var/lib/private/lnk/, the private state alias used by systemd-managed services.

Runtime Sockets

With XDG_RUNTIME_DIR set, sockets live under its lnk/ directory. Otherwise Linux uses /run/user/<uid>/lnk/ when available; the fallback on either operating system is /tmp/lnk-run-<uid>/. These are runtime locations. Stop the processes using them before verifying their removal.

Shell and Package-Manager Records

If you add the installer's suggested PATH entry, it goes in ~/.bashrc or ~/.zshrc, depending on your shell. Cargo installations also have executables in the chosen Cargo installation's bin/ and package-manager records; Homebrew tracks its own installation. Installation Methods explains these differences. Remove only the Link-specific entries and use the package manager's records to identify what it installed.

A Secret, Start to Finish

A secret is any value kept private, such as an API key. Following one shows where each piece of it lives.

Made

lnk secret create STRIPE_KEY asks for the value. On a Mac the value goes into your login Keychain. On Linux, an installed secret keeper holds it in /var/lib/lnk/secret/ under its own user. Without that keeper, the value stays in your user-owned ~/.lnk/safe/secrets/secrets.toml with mode 600. The Secrets guide explains the store choice and what each protects.

Given

lnk secret add STRIPE_KEY --to agent:main gives it to the agent: it adds a grant to the active store, naming the service the agent acts as. Nothing in the agent's own folders changes, so the agent can't grant itself a secret by editing a file it can reach.

Used

lnk agent start main sets up the agent's secret route. A named route checks the current store and grant on each call, and the bridge adds the sealed secret only to allowed requests for its host. The agent's run never sees ~/.lnk/safe or the value added outside its sandbox.

Moved with Its Agent

An agent's own credentials, its model credential and its connections' tokens, go with it when it moves (lnk agent move), sealed to the machine it goes to. A secret you granted by hand stays here. Grant it again where the agent runs.

Deleted

lnk secret delete STRIPE_KEY removes the value and its entry at once. Deleting the agent removes its own credentials with it.

An Agent, Start to Finish

An agent has a folder in each part, and each part keeps a different side of it.

Made

lnk agent create main writes its settings to ~/Link/Safe/Agents/main/, where you can read and edit them, and makes ~/Link/Agents/main/home, the folder of files it works in. Link's own records of it, its ID and service, go in ~/.lnk/safe/agents/. Each harness it runs gets a home under ~/.lnk/data/agents/main/harnesses/.

Deleted

lnk agent delete main removes its harness homes, memory, conversations, settings and credentials. Its work files stay unless you add --delete-files. A deleted agent's state is kept as one archive in ~/Link/Archive, and what an agent that moved away left is kept in ~/.lnk/data/agents/move/.

Your Files, Logs and Archive

Three folders in ~/Link belong to no single owner.

  • ~/Link/Files is for your own files, which storage backs up (Storage).
  • ~/Link/Logs keeps the record of each command you run.
  • ~/Link/Archive keeps what's gone, in a folder for each owner.

Moving a Location

Every location has a stable ID, such as link.files or lnk.agent-data. The map, ~/.lnk/safe/map.toml, records where each location is on this machine. Link writes every ID the first time it starts, so a later release that changes a default leaves your machine as it is. The map itself always stays at the same path.

Set a Location

lnk folder set moves a location and everything inside it, then updates the map. Here the Link folder moves into Documents:

lnk folder set link ~/Documents/Link

When you already moved the files yourself, the same command points Link at their new place. When the Link folder isn't where the map says, the next lnk command asks where it went, or whether to make a new one with lnk folder create. Link never searches the disk for it.

What the Map Refuses

Reading the map refuses an entry that would weaken the folders' kinds:

  • Control outside a Safe, where a run could reach it.
  • A program outside ~/.lnk/exec.
  • Data inside a Safe or exec.
  • Two locations that overlap where their defaults don't.

The map names its schema, schema = 1, and a map written by a newer release is refused with a request to run lnk upgrade.

Every Location

Each entry is a location in layout.toml: its default path, its kind, its owner and its ID in the map. Paths are the defaults a new machine starts with, and lnk folder list shows this machine's.

  • ~/.lnk/data/agents/context: data, agents', location lnk.context
  • ~/.lnk/data/agents/harness-history: data, agents', location lnk.harness-history
  • ~/.lnk/data/agents/memory: data, agents', location lnk.shared-memory
  • ~/.lnk/data/agents/move: data, agents', location lnk.agent-move
  • ~/.lnk/data/agents/shared-harnesses: data, agents', location lnk.shared-harnesses
  • ~/.lnk/data/agents: data, agents', location lnk.agent-data
  • ~/.lnk/data/archives: data, Link's own, location lnk.archive-staging
  • ~/.lnk/data/bundles: data, bundles', location lnk.bundles
  • ~/.lnk/data/harnesses/claude: data, harnesses', location lnk.claude
  • ~/.lnk/data/harnesses/codex: data, harnesses', location lnk.codex
  • ~/.lnk/data/harnesses/configured: data, harnesses', location lnk.configured
  • ~/.lnk/data/harnesses/openclaw/doctor-release: data, harnesses', location lnk.openclaw-doctor-release
  • ~/.lnk/data/measures/measures.jsonl: data, measures', location lnk.harness-measure-log
  • ~/.lnk/data/models/context: data, models', location lnk.model-context
  • ~/.lnk/data/teams: data, teams', location lnk.team-memory
  • ~/.lnk/exec/agents/shims/mktemp: exec, agents', location lnk.mktemp
  • ~/.lnk/exec/agents/shims: exec, agents', location lnk.shims
  • ~/.lnk/exec/bin/lnk: exec, Link's own, location lnk.core-program
  • ~/.lnk/exec/bin: exec, Link's own, location lnk.bin
  • ~/.lnk/exec/harnesses/claude: exec, harnesses', location lnk.claude-programs
  • ~/.lnk/exec/harnesses/codex: exec, harnesses', location lnk.codex-programs
  • ~/.lnk/exec/harnesses/deepseek: exec, harnesses', location lnk.deepseek-programs
  • ~/.lnk/exec/harnesses/hermes: exec, harnesses', location lnk.hermes-programs
  • ~/.lnk/exec/harnesses/openclaw: exec, harnesses', location lnk.openclaw-programs
  • ~/.lnk/safe/agents/bridges: control, agents', location lnk.shared-bridges
  • ~/.lnk/safe/agents/credentials: control, agents', location lnk.agent-credentials
  • ~/.lnk/safe/agents/environments: control, agents', location lnk.agent-environments
  • ~/.lnk/safe/agents/harness-grants: control, agents', location lnk.harness-grants
  • ~/.lnk/safe/agents/ids.toml: control, agents', location lnk.agent-ids
  • ~/.lnk/safe/agents/installations: control, agents', location lnk.installations
  • ~/.lnk/safe/agents/journal: control, agents', location lnk.migration-journal
  • ~/.lnk/safe/agents/machines: control, agents', location lnk.agent-machines
  • ~/.lnk/safe/agents/places: control, agents', location lnk.agent-places
  • ~/.lnk/safe/agents/policy.toml: control, agents', location lnk.agent-policy
  • ~/.lnk/safe/agents/services.toml: control, agents', location lnk.agent-services
  • ~/.lnk/safe/agents/stopped-services: control, agents', location lnk.stopped-services
  • ~/.lnk/safe/agents/store-scratch: control, agents', location lnk.store-scratch
  • ~/.lnk/safe/agents/transfers/held: control, agents', location lnk.held
  • ~/.lnk/safe/agents/transfers/moved: control, agents', location lnk.moved
  • ~/.lnk/safe/agents/transfers/moving: control, agents', location lnk.moving
  • ~/.lnk/safe/agents/transfers/receiving: control, agents', location lnk.receiving
  • ~/.lnk/safe/agents/transfers/restore: control, agents', location lnk.restoring
  • ~/.lnk/safe/agents/transfers/scratch: control, agents', location lnk.transfer-scratch
  • ~/.lnk/safe/agents/transfers/sending: control, agents', location lnk.sending
  • ~/.lnk/safe/agents/transfers/teams: control, agents', location lnk.team-moving
  • ~/.lnk/safe/agents: control, agents', location lnk.agents
  • ~/.lnk/safe/approvals: control, Link's own, location lnk.approvals
  • ~/.lnk/safe/artifacts: control, Link's own, location lnk.artifacts
  • ~/.lnk/safe/aws: control, aws', location lnk.aws
  • ~/.lnk/safe/boxes/machines: control, boxes', location lnk.box-machines
  • ~/.lnk/safe/boxes: control, boxes', location lnk.boxes
  • ~/.lnk/safe/bundles/signers: control, bundles', location lnk.bundle-signers
  • ~/.lnk/safe/clouds/prices: control, clouds', location lnk.prices
  • ~/.lnk/safe/clouds: control, clouds', location lnk.clouds
  • ~/.lnk/safe/envs/jobs: control, envs', location lnk.jobs
  • ~/.lnk/safe/envs: control, envs', location lnk.envs
  • ~/.lnk/safe/gcp: control, gcp', location lnk.gcp
  • ~/.lnk/safe/machine.toml: control, Link's own, location lnk.machine
  • ~/.lnk/safe/maintenance.toml: control, Link's own, location lnk.maintenance
  • ~/.lnk/safe/map.toml: control, Link's own, never mapped
  • ~/.lnk/safe/measures/credentials: control, measures', location lnk.measure-credentials
  • ~/.lnk/safe/measures/measures.jsonl: control, measures', location lnk.measure-log
  • ~/.lnk/safe/measures: control, measures', location lnk.measures
  • ~/.lnk/safe/models/facts.toml: control, models', location lnk.model-facts
  • ~/.lnk/safe/modules/offers.toml: control, Link's own, location lnk.module-offers
  • ~/.lnk/safe/modules: control, Link's own, location lnk.modules
  • ~/.lnk/safe/releases/update.json: control, Link's own, location lnk.update
  • ~/.lnk/safe/releases: control, Link's own, location lnk.releases
  • ~/.lnk/safe/sandboxes/grants: control, sandboxes', location lnk.sandbox-grants
  • ~/.lnk/safe/sandboxes: control, sandboxes', location lnk.sandboxes
  • ~/.lnk/safe/secrets/preferences.toml: control, secrets', location lnk.secret-preferences
  • ~/.lnk/safe/secrets/secrets.toml: control, secrets', location lnk.secrets
  • ~/.lnk/safe/services: control, Link's own, location lnk.services
  • ~/.lnk/safe/settings.toml: control, Link's own, location lnk.settings
  • ~/.lnk/safe/storage: control, storage', location lnk.storage
  • ~/.lnk/safe/teams: control, teams', location lnk.teams
  • ~/.lnk/safe/upgrades: control, Link's own, location lnk.upgrades
  • ~/Link/Agents: data, agents', location link.agents
  • ~/Link/Archive: data, Link's own, location link.archive
  • ~/Link/Boxes: data, boxes', location link.boxes
  • ~/Link/Files: data, Link's own, location link.files
  • ~/Link/Logs: data, Link's own, location link.logs
  • ~/Link/Safe/Agents/defaults.toml: control, agents', location link.agent-defaults
  • ~/Link/Safe/Agents: control, agents', location link.agent-settings
  • ~/Link/Safe/Models/models.toml: control, models', location link.models
  • ~/Link/Safe/Sandboxes/presets: control, sandboxes', location link.sandbox-presets
  • ~/Link/Safe/Teams: control, teams', location link.team-specs
  • ~/Link/Safe/folder.toml: control, Link's own, location link.marker
  • ~/Link/Safe/settings.toml: control, Link's own, location link.settings
  • ~/Link/Safe: control, Link's own, location link.safe
  • ~/Link/Teams: data, teams', location link.teams
  • ~/Link: data, Link's own, location link

A Module's Own Folders

A module released apart from Link keeps its folders in ~/.lnk too, in its own folder by its word, and lists them in its own documentation rather than here. They aren't on the map, so lnk folder set doesn't move them.