Routes
link-sandbox-route: a route, a way out of a sandbox beside the
network, which its proxy mounts under /_link/ and a bridge outside
serves (Interface).
A route
Each of a proxy's routes (link_sandbox_route::Route) is a way out
beside the network, {"name", "prefix", "needs_url_secret"?, "ports"?, "bridge": {"socket", "start"?}, "given", "env"?}.
Where it's mounted
The proxy mounts it at /_link/<prefix> (behind /_link/url/<secret>/
with needs_url_secret), and hands each call to it, with given, to
the bridge at socket, started by start when nothing serves it there
(Routes' bridges). env is what the program is told
of it, {proxy} in each value its address.
caller
caller (link_sandbox_bridge::Binding, {"identity", "key"}) is who calls
the routes, which the proxy proves on each call. With routes and none,
wrap binds one for the run, run-<name> in this machine's keyring,
which the proxy unbinds as it ends.
Placeholders
The program reaches the hosted model at
link_model_contract::models::route::url with the key's placeholder,
a local model at local_url, and a secret's service at
link_secret_contract::secrets::route::url with the secret's
placeholder. Each is made by link_sandbox_route::Placeholders,
random for each run and holder, and refused by the route's bridge unless
it's one; a secret's Sealed says where it may be sent and what is
refused.
model
A hosted model's key (link_model_contract::models::route::hosted):
given is {"provider", "key": "model" | "fallback", "placeholder", "server_tools"?}, naming the caller's key, never holding it.
secret
Secrets each added to its own service's calls
(link_secret_contract::secrets::route::route): given is
{"granted"?: [{"name", "kept": {"own": <use>} | {"variable": <name>} | {"token": {"grants"}}, "placeholder", <rule>}], "secrets"?: [{"name", "value", "placeholder", <rule>}]}.
Its rules
Each rule is "host", "paths": [{"prefix", "rest"}], "header"?: {"name", "value", "basic"?}, "refuse"?, "methods"?, "public"?.
granted and secrets
granted names a secret the store grants the caller, and secrets
hands a run's with its value, never in a file: a routes file holding one
is refused, written or read.
Kept by the keeper
A keeper-backed secret route replaces given with an opaque HPKE
grant before proxy handoff, so proxy configuration holds ciphertext for
this route. The keeper's secret bridge opens it only for the bound
socket UID, agent, owner, proof and current grant. Root binders can name
the helper UID; ordinary callers can name only their own.
local-model, mcp and open
local-model is this machine's runtimes at ports, inference only
(local). mcp is tools that run outside (link_sandbox_client::routes::tools,
{"tools", "desktop"?}), and open pages opened in your browser,
asking you (open, {"hosts", "desktop"?}, ["*"] any).
Routes' bridges
lnk-model bridge, lnk-secret bridge and lnk-sandbox bridge,
each `--socket --keys --settings
How one starts
The first proxy whose route needs it starts it (bridge.start) with
the system's PATH, <dir> as LNK_MACHINE_DIR and its home folder
as HOME. Where systemd runs Link's services and a user manager is
reached, that's a transient user unit, lnk-bridge-<module> (systemd-run --user --collect), its stderr appended to <module>.log beside its
socket, and elsewhere a process group of its own. A lock keeps it to
one. It exits once idle, once its socket isn't its own, or once an
upgrade replaced its program and no call is in flight.
A call
It serves link-sandbox-bridge's stream call, each proved as an agent bound in
<keyring>. The action is link_sandbox_route::Call ({"route", "sandbox", "upstream", "listed"?, "given", "to": {"request": {"head"}} | {"port": {"port"}}, "inbound"?}): the route's name, the sandbox's,
where its traffic leaves from, whether its call's host is one of the
sandbox's own, what the route is given, and the request's head, or a
port of the route's to reach. Then comes the request's body as it
comes.
Its verdict
The bridge answers one JSON line, link_sandbox_route::Verdict
({"to"?, "outcome": "allowed" | "refused" | "failed"}, where it goes,
never a path, which the proxy logs), or link-sandbox-bridge's error envelope,
then the answer, as it comes.
model and secret
Both read a key or secret the route names from the store at each call
(link_secret_contract::for_agent, of the caller's service), refusing one
the store doesn't grant the caller, or whose placeholder wasn't made for
its value. secret adds each secret to its own service's calls by its
rule, refusing the rest.
Agent tokens
An agent token may carry an assertion ({url, proof}) beside its
kept selector. The trusted bridge trades that agent-specific proof at
the issuer with {resource, grants} and adds its returned access token
outside the sandbox. It trades at every call, follows no redirect and
refuses an expired token or failed exchange. Such routes are handed
directly to the proxy and cannot be saved as names alone in a file.
model's answers
model adds the hosted key to a request showing its placeholder, its
provider's tools that run on its servers removed, and adds each
answer's token counts to the caller's mapped Hidden::MeasureTokens
folder (~/.lnk/safe/measures/credentials by default), <agent ID>.json (600, link_measure_contract::client::Tokens,
link_measure_contract::client::tokens, under a lock), which lnk measure reads as the agent's.
local-model and sandbox
local-model sends inference alone to ports; sandbox serves mcp
(each tool, asking you where its calls aren't allowed) and open,
asking you before each page.
What mcp and open reach now
given names what a call may reach as its proxy started; the bridge
never trusts it alone. At each call it asks the modules that keep agents
sandbox.grants (link_sandbox_client::grants, {"agent", "sandbox"},
answered {"agent": {"tools", "browser"?}} or "not_mine") what the
agent the call is proved as may reach now, and a call reaches only what
both say. A tool or a page's host taken back since is refused. A
person's own run, bound as run-<name>, reaches what its routes say.
A keeper that doesn't answer
An agent no module answers for, or whose keeper fails to answer,
reaches nothing. Its mcp call is refused with that reason in the
keeper's own words, such as a module built from other sources than the
bridge, and the steps that help: lnk upgrade for a module from
another build, lnk agent restart for a keeper that didn't answer.
Only a tool its keeper didn't grant is refused as one the sandbox isn't
granted now.
A keeper that isn't a module
A service that binds agents into sandboxes, where no module keeps them,
writes what each may reach as it binds it (grants::keep): the same
{"tools", "browser"?}, in state/sandbox/grants/<agent>.json of the
settings its bridges serve, and takes it back (grants::forget) as it
lets the agent go. The bridge reads that file only when no module keeps
the agent, and never when a module failed to answer.
Models and Secrets
Models and Secrets explains placeholder replacement, credential handling, and the bridge's responsibility when a route reaches a model or a service that requires a secret.