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/s/<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_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.
An agent's own token
{"token": {"grants"}} is no secret of the store: the bridge adds the
caller's own access token for the rule's host, sub agent:<its ID>,
granted grants there, which lnk auth token --agent-id makes as the
machine signs for it (The Access
Token).
It keeps each until a minute before it ends, never in a file, so the
agent reaches a service across a network as itself and never holds the
token. The keeper's bridge makes none.
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 model bridge, lnk-secret secret bridge and lnk-sandbox sandbox bridge, each `--socket --keys --settings
How one starts
The first proxy whose route needs it starts it
(link_sandbox_route::Route's bridge.start) in a process group of its
own, its environment the system's PATH, <dir> as LNK_MACHINE_DIR
and its home folder as HOME alone. A lock beside its socket keeps it
to one, and it exits once no call has come for a while, or its socket is
no longer its own.
A call
It serves link-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-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 agent), 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.
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 <dir>/measure/tokens/<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.