Files

link-files is how Link keeps files on this machine: its folders, and reading and writing them so no other user can swap, read or change what's in them.

Home and Hidden

Link owns two roots: Home, ~/Link, for the person, and Hidden, ~/.lnk, for implementation state. Link creates no persistent hidden file or folder in Home. Binary indexes remain visible with the data they describe. The shared Rust API is link_files::layout.

The path catalogue

layout.toml defines the roots and every fixed location. Home and Hidden are typed location identifiers. Their path() and try_path() methods resolve the appropriate root; relative() reads its registered path. Callers add only their own names and files below a location, rather than rebuilding a root path.

Explicit roots

Hidden::Machine.at(root) reads the map in machine folder root, and Home::Settings.at(root) reads this machine's map when root is the Link folder it names. at_default(root) is the layout's default under root, as a new machine has it. Hidden::OpenClawDoctored.in_home(home) resolves an isolated harness's state without consulting LNK_MACHINE_DIR. Root::Home.default_in(home) names the default Home root without reading or creating files. The catalogue refuses hidden components in every Home location.

Trust Boundaries

Each location declares a typed control, exec or data boundary. Control must be in a Safe, installed code in exec, and granted data in data. A module cannot claim the core owner link.

Owner Files

seen_specs(owner) names the specs an owner (sandboxes) has observed, inside its own Safe. The filename is shared layout data, and each module supplies its owner's word rather than adding a global specs folder.

Harness homes

Each agent's folder in Hidden::AgentHomes holds its harnesses' homes, one each, in the folder layout.toml's [agents] harness-homes names. harness_homes_at(hidden, agent) names that folder under an explicit Hidden root. in_harness_home(path, hidden) says whether a path is a harness's home or inside one, an agent's own or the one its owner's agents share in Hidden::SharedHarnesses, never the folder of them or the rest of the agent's folder. Harness homes are data, granted separately from protected control and programs.

Installed Programs

exec_in(location, home) selects an adapter's program tree. Link hands the adapter LNK_EXEC_DIR, first naming its private runtime staging and then a published directory under exec/harnesses/<harness>/<agent>/<adapter hash> (harness_exec(harness)). A relative or traversing handoff is refused. This value grants no access. Link supplies the sandbox's read-only grant independently.

Publication

An installer writes its own staging while it runs. After it exits, Link copies its output through directory handles, relocates staged paths and publishes a complete tree. Copying follows no source link. An adapter version has its own tree, so publishing another leaves running agents' programs in place. A run never receives write access to installed programs.

Memory Runtime

MemoryService::at(folder) names a memory service's writable runtime, generated handoff and storage sockets from the same catalogue. in_memory_runtime(path, hidden, write) checks a resolved grant against those areas. Only run/ is writable. Generated agents-<generation>.json handoffs and bridges/ are read-only, while agent records, generation caches and service logs remain closed. The sandbox refuses any other grant inside Hidden::SharedMemory.

Root accessors

home_dir() names the operating system user's home, with . as its missing-HOME fallback. try_home_dir() requires an absolute HOME and resolves a linked home before use. machine_dir() and try_machine_dir() name Hidden. An absolute LNK_MACHINE_DIR selects a process's isolated Hidden root, whose map locates Home.

Temporary security probes

lnk sandbox check may temporarily create native dotfile probes in writable folders, including Home, to test confinement. These probes are the exception to the visibility rule and are removed after checking. See temporary native names.

Owners and the Map

Two declarations shape every path: whose folder a location is in, and where it is on this machine.

Owners

Each location also names its owner, a word of [owners] or link for Link's own. An owner has one folder in each part it declares, named by its plural word, Title Case directly in ~/Link or its mirror ~/Link/Safe (~/Link/Agents, ~/Link/Safe/Models) and lowercase everywhere else (~/Link/Safe/Sandboxes/presets).

What the Layout Refuses

Layout::validate refuses a location outside its owner's folder, Link's own inside one, and an owner whose folders don't match its declared parts, so each path has its twin in the others or is declared one-sided. reserved(owner) names what the layout keeps in an owner's folder, which none of its things may be named.

The Map

Each location's path on a machine is the map's, ~/.lnk/safe/map.toml (layout::map). It maps a location's stable key (link.files, lnk.agent-data, or link for the Link folder) to a path relative to its root, or an absolute one for data kept elsewhere. The map is at a fixed path, Hidden::Map, the one location never mapped. lnk folder list and lnk folder set are its commands (Where Link Keeps Things).

Pinning

prepare() pins every key not yet in the map to layout.toml's default, under its lock, so a later release changing a default leaves an existing machine as it is. map::set moves a location's files and its entry with every entry inside it, or only the entry when the files already moved.

First Need

Folders are created on first need. Reading a path or printing a spec creates no control roots or map. Before untrusted code starts, layout::prepare() protects Hidden's Safe and installed programs, and Home's Safe when Home exists. A missing Home stays absent until an operation needs it, so moving the Link folder outside Link does not recreate its old path before lnk folder set link selects the moved folder.

Refusals

map::load refuses control outside a Safe, code outside exec, data inside either, an overlap the defaults don't have, an unknown key, and a schema newer than this release's.

Renamed Locations

A location's key is stable, but a release may rename one: the new name in layout.toml, and a step in the map's schema, src/layout/map/schema.toml, renaming its entry, its key quoted since it holds a dot ('locations."link.documents"' = 'locations."link.files"'). An older map advances through the step as it's read, its path and comments kept, so Key::parse sees only current names and an old one is refused as no location. An archive's [map] names locations too and follows by the archive's own step.

Saved Files

Every file Link saves names its schema: settings, state, grants, approvals, the ID ledgers and the map, each at version 1 at launch. Its owner declares it with link_files::specification! beside its type, naming a schema.toml that holds its kind, its current schema and its steps, the same declaration a spec's owner writes (Specifications). The steps engine is link_files::schema, which link-spec re-exports.

Reading and Writing

saved::read and read_optional read a TOML file as control and advance it through its steps, and saved::write writes it whole with schema first. parse_json and print_json do the same for a JSON object, its steps applied to its keys. advance gives the current text to an owner that parses it itself, as the secret store does so its errors never show a value. A saved file with no schema is the current one, a spec file with none is refused, and one written by a newer release is refused, naming lnk upgrade.

Line Ledgers

A file Link only appends to, a line at a time, names its schema on every line: saved::line writes a value as one JSON line with schema last, and parse_line reads one, advancing it, so a ledger written across an upgrade holds lines of two schemas, each read by its own. A line a newer release wrote is refused, naming the upgrade, never skipped. The repository's saved check refuses a bare line appended to a file.

Upgrades

Reading never rewrites a file: the release reads an old schema through its steps in memory. A step that renames, removes or refuses a key is declared data in the owner's schema.toml, never a branch in its code. lnk upgrade converts each file of state to the current schema after your yes, runs the transfers that move records to their new owners, and never rewrites history (Upgrades).

Steps That Run Code

A change no rename, removal or refusal can say is a step that names its owner's code, kept in the owner's migrations/ folder (Migrations).

The Home Tree

Home keeps editable control in Safe, with work and records beside it. Each agent's TOML and grants live in Safe/Agents/<name>, its work in Agents/<name>/home, and its collections in agent. Link's own files sit at the root of Safe, Logs and Archive. A box on this machine with no VM works in its own Boxes/<name>/home. Safes are made private before starting a run, and no run reads or writes them.

Link/
├── Safe/
│   ├── folder.toml
│   ├── settings.toml
│   ├── Agents/main/
│   ├── Agents/defaults.toml
│   ├── Teams/
│   ├── Models/models.toml
│   └── Sandboxes/presets/
├── Agents/main/
│   ├── home/
│   ├── agent/
│   └── Memory/
├── Teams/research/
├── Boxes/here-1/
│   └── home/
├── Files/
├── Logs/
└── Archive/

The Hidden Tree

Hidden separates trust boundaries, with one owner beneath each. Link starts fresh in this layout and reads no control from data. Installed programs are writable only outside a run, and a run reads only the programs its grants name.

.lnk/
├── safe/
│   ├── map.toml
│   └── <owner>/
├── exec/
│   ├── bin/
│   └── <owner>/
└── data/<owner>/
  • Control: safe's own files are the core's, and each owner has its own protected folder.
  • Exec: exec/bin holds only what goes on PATH, lnk and its modules, with harness installations and shims under their owners.
  • Data: harness homes, portable continuation and memory live under data, where a caller may grant them.

Runtime Locations

Sockets live under Root::Runtime, apart from persistent state. Link uses XDG_RUNTIME_DIR/lnk, or /run/user/<uid>/lnk on Linux when that folder exists. Runtime identifies each module's socket locations, while at(root) supplies an explicit runtime root to a bridge.

Short Runtime Folder

A machine with neither, such as a Mac, uses /tmp/lnk-run-<uid>, never a folder under $TMPDIR. A Unix socket's path must fit the system's sun_path field, which holds 104 bytes on macOS. A Mac's $TMPDIR (/var/folders/<2>/<28>/T/) takes about 50 of them, which left a shared tool's socket too long. The [runtime-root] table of layout.toml declares the parent and prefix.

Private in a Shared Folder

Every user can write /tmp, so Link makes the folder this user's alone (mode 700) before it makes anything inside it. A link or another user's folder already at that path is refused, never used.

System Locations

System names root-owned settings, state and exec from the same catalogue. SystemRoot names their parents. State uses /var/lib/lnk on Linux and /var/db/lnk on macOS; settings use /etc/lnk and programs /usr/local/lib/lnk. path_for(SystemOs) resolves another platform without consulting the host. Each location declares its trust kind; control cannot be placed in the exec root or code in state.

Shared System Parents

Private directory creation below the system's settings, state and program roots prepares the root-owned shared parent with [system] shared-mode. Each parent stays searchable by separate service users, while each service keeps its own children private. An untrusted parent is refused before creation or permission changes. A shared root cannot itself be made private through create_private_dir.

System Sandbox Boundaries

system_safes() includes the settings root and every control location in state, including systemd's private state aliases on Linux. System::paths_for(os) lists a location's primary path and its aliases. Sandboxes keep these closed even under a grant of their parent, and installed system programs remain read-only. A run never creates or changes the host's system roots.

State the catalogue doesn't name

State is control unless the catalogue declares it data. So every folder already in a state root that no data location is in is closed too, and a module whose state this catalogue doesn't name stays closed to runs. The state root's data part, System::Data (/var/lib/lnk/data on Linux), is where an owner keeps state a run may be granted, in its own folder by its plural word, as in ~/.lnk/data.

Places an owner declares

The catalogue names only Link's own system locations. A module that is released apart from Link declares its own in a TOML file beside its code. Each is a SystemPlace, one of the system roots (settings, state or exec) and a relative path under it, refused as it's read when the path leaves its root. system_places reads the owner's file into its own type once, and SystemPlace::paths_for(os) gives its path and aliases as the catalogue's do.

Folders an owner declares in ~/.lnk

A module released apart from Link declares its folders in ~/.lnk in the same file, each a HiddenPlace: its kind (control, data or exec) and its path in ~/.lnk. It's refused as it's read unless the path is in the part its kind is in (safe/, data/ or exec/), in a folder of its owner's that no owner of [owners] has and that isn't Link's own. Its path, at(hidden) and in_home(home) give its path as a Hidden location's do.

Not on the map

It isn't on the map, which pins the catalogue's locations, so it's always at its declared path in this machine's ~/.lnk. The public catalogue never names it, so a module that isn't public keeps its folders to itself.

Shared state locations

Link-owned persistent state lives below .lnk in the relevant home, including an isolated harness home. state::path(home, area) selects a typed Hidden location from the same catalogue. The inventory below covers those isolated-home locations; the catalogue also holds the host's and Home's locations.

Portable Context and Configuration

~/.lnk/data/agents/context is the isolated home's portable agent context. ~/.lnk/data/harnesses/configured records completed harness configuration, and ~/.lnk/data/harnesses/openclaw/doctor-release records OpenClaw's setup marker. These paths come from state::Area, so adapters use the selected home rather than inventing another hidden directory beside .lnk.

Execution Records

~/.lnk/data/measures/measures.jsonl receives a harness's own measurements. ~/.lnk/safe/envs/jobs contains job state, including bare-job workspaces. A location's control or data kind comes from the shared layout catalogue, and selecting an isolated home does not change that classification.

Private folders and writes

What Link writes that may hold a secret is readable by this user alone, in folders no other user made first.

create_private_dir

Creates a folder readable only by this user (0700 on Unix), with any missing private parents (also 0700), and takes away others' permissions from one already there. A folder, or a link to one, that another user owns is refused: in a shared folder such as /tmp they could have made it first, to swap what's put in it. check_own_dir refuses a folder that isn't this user's, itself and not through a link to another's. Shared system roots retain their catalogue mode and are refused as the requested private directory.

write_private

Writes a file readable only by this user, atomically, creating its folder (0700) if it is missing; an existing ~/.lnk is made private too. The staged file is synced before renaming, then its parent is synced before success is returned. Two writes at once each leave the file whole, the last one's; a caller that reads, changes and writes it back holds a lock of its own. layout::temporary_name() gives each atomic write a visible sibling name, preserving same-filesystem renames even outside Hidden.

Abandoned Staging

Before a run, Link removes regular lnk-tmp-* files older than seven days from this user's Safes, at most once per day. Both bounds are in layout.toml's [temporary]. It never follows a linked directory or removes a staged file while its write_private transaction is active. Other users' folders and shared writable Safes are skipped. The sweep is best effort: a folder it can't read, or one deeper than 32 folders, is left as it is and named in a warning, and the sweep is still recorded, so it never stops the command that started it.

Staging in Data

Old staging in data is only listed by lnk folder check, with --json for an array of paths. It is never deleted. The scan covers the catalogue's data roots owned by this user and skips linked directories. The core's Safe keeps the last completed sweep in maintenance.toml; deleting it permits a new scan on the next start.

lock_file

Holds a lock file until it's dropped, and the next to ask waits. Its folder is made private, and the file is opened in place, never replaced and never through a link (O_NOFOLLOW), 0600, so every holder locks the same file.

private_temp_dir and random_token

private_temp_dir(name) is a new folder in the system's temporary folder, lnk-<name>- and a random suffix, 0700, made here and now (as mkdtemp): never one another user made first. random_token() is 32 random hex characters, for tokens and secrets Link makes, such as a harness's local API key, a pairing code or a proxy's tag.

write_program and copy_program

Write or copy a program (mode 755), never open for writing in this process: one this process wrote itself could fail to run ("Text file busy") while a child another thread forked still held the write open, so a short-lived install writes it, from a copy this process wrote and never runs.

Reading Files

Trusted opens establish who could have written a file. Read receipts identify which source bytes and returned text a reader observed.

Reading a file whose writer matters (fs)

read_trusted reads a file once, where it really is, and no more of it than a limit, naming that limit's owner in its error. A link is followed once, here, and the file opened with no link left and checked to be the one its real path names, so a folder swapped on the way opens nothing else.

Trust

Who it must have been written by: the users who may own it, and with ancestors each folder on its way, a folder its others write let by only with its sticky bit, as /tmp; the mode bits none may have, 0o022 by default; and with no_link, a link at its path refused instead of followed.

What it refuses

It's opened without waiting, so what isn't a file (a pipe put there) is refused, never waited on. A missing file is an error whose root cause is that io::Error.

Text Read Receipts

reading::ReadReceipt identifies the source snapshot and the exact text a reader returned. Its SHA-256 digests include byte lengths. A source is either whole or a bounded prefix, and an exclusive byte span locates the selected source before normalization. Composable transformations identify line normalization, lossy UTF-8 decoding, and whitespace trimming.

Returned Text

A presentation prefix, such as a pagination label, is counted separately. validate checks its UTF-8 boundary, the selected text's digest, and the source bounds. covers_source describes source coverage only. A prefix or lossy decoding never covers the whole source, and a later consumer must also account for any delivery limit. The receipt establishes neither the reader's authority nor what a model received.

Typed settings

settings::read reads bounded typed TOML through checked directory and file handles. Control files refuse final links, linked data ancestors and hard links. Only catalogued root-owned OS aliases in immutable system parents may be traversed, with their targets checked the same way. Missing documents use defaults only after every existing ancestor passes. The user's home and the system roots may themselves be reached through a link, resolved once before the walk (Linked Roots).

Control Reads

fs::read_control applies the same policy to non-TOML control, allowing this user or root to own it. Trust::control supplies that policy for an explicit owner set. fs::checked_parent returns the pinned parent for handle-relative operations. These APIs and their limits are described in File Security.

Writer locks

settings::read_optional distinguishes a missing file from an existing document. settings::lock gives writers a stable sidecar lock after checking the document's trust, so atomic replacement does not let two writers hold different locks for the same settings.

Folders another may write (nofollow)

A harness's folder, an agent's Home or a skill's download, walked by lnk outside the sandbox without following a link. Each name is opened relative to its folder's handle (Dir) with O_NOFOLLOW, so a link swapped in after a check is refused rather than followed, and a file is read or written through the handle it was opened as.

Traversing a private parent

Dir::search_unlinked opens a parent for access to its children without following a link at the parent. On macOS it uses O_SEARCH, so a sandbox can grant selected children without letting the harness list their parent. Children are opened separately with their own access checks.

Passing through to a folder

Dir::root_to_pass and Dir::passing walk from / to a folder without reading the folders above it: each is opened only to pass through (O_PATH on Linux, O_SEARCH on macOS), made first when asked and missing. A sandbox that grants only the folder at the end, as Landlock and Seatbelt do, then lets the walk through. A handle opened this way takes the *at calls alone, so the folder at the end is opened with Dir::folder or Dir::create_folder to be read, locked or synced.

Opening a file

Dir::open_file refuses a link and a device without waiting on it. Opened to write, a file with another name too (a hard link) is refused, since what's written here would be written there, and O_TRUNC is refused, since it would empty that other name before the refusal.

Copying and removing

Dir::remove_all and Dir::copy_into go at most DEEPEST, 32 folders down, and refuse a folder past it. A removal first gives the owner of each folder of this user's the right to write and search it, on its handle, so read-only folders such as Go's module cache (0555) can be emptied. It removes all it can past a name it can't, and its error names the first left by its path. A copy says what it does with a link: made again as the same link, left out, or refused, nothing of it written, and reports what it copied and left out.