Standalone mode¶
In standalone mode an agent has no Fadenstack server. It talks to the person's own AI server, any server that speaks the OpenAI chat completions API (Ollama, LM Studio, vLLM, SGLang, llama.cpp, LiteLLM, OpenRouter, an OpenAI-compatible cloud). The agent's definition, its tools, its approvals and its chats all stay on the device. The .NET SDK has the same mode (Parity).
import { EndpointDialect } from "@fadenstack/client";
import { AgentDefinition, FadenstackAgent } from "@fadenstack/agents";
const agent = FadenstackAgent.createBuilder()
.useEndpoint({
baseUrl: "http://localhost:11434/v1",
model: "qwen3:14b",
dialect: EndpointDialect.ollama,
// key: a TokenProvider over the app's own key store; leave it out for a server without a key
})
.useLocalProfile(AgentDefinition.fromJson(definitionJson))
.build();
The person connects through the connection wizard, which does the steps below and gives the app a
ConnectionResult. An app that does not use the wizard does them itself.
The model¶
useEndpoint(endpoint, report?)makes the person's endpoint the model.reportis the endpoint check's result, if the app kept one: it says whether the model sees pictures.useChatStreamer(streamer)makes anyChatStreamerthe model instead, for an app that has its own client. The agent never closes it. A machine policy that lists endpoints refuses it, because it names none.- Both need
useLocalProfile, and neither goes withuseServeroruseClient.build()throws if you mix them. - The machine policy can forbid standalone (
standalone), allow only listed endpoints (endpoints) and forbid plain http in the local network (plainHttp).build()throwsMachinePolicyErrorfor what it forbids.
The agent's definition¶
AgentDefinition.fromJson(json) reads the app's own definition, in the shape of the server's agent body. It stands in
for the server's profile:
| Field | Meaning |
|---|---|
slug |
Required: lower-case letters, digits and inner hyphens, at most 64 characters. The agent's data is kept under it. |
name, description |
The agent's name (the slug when there is none) and a description. |
version.instructions |
The agent's own instructions. The person's own instructions, if any, come after them. |
version.host_tool_contract |
The host tools the agent may offer, each with its class (risk). A tool with no risk, or an unknown one, is unclassified and asks every time. |
version.local_mcp_mode, version.local_skills_mode |
allow or disable. Anything else is disable. |
version.ui |
The greeting, suggestions and the rest of the interface settings. |
model_alias is ignored. Every other field is kept, so a definition from a newer app reads and writes back whole.
useLocalProfile(definition, ownInstructions?, options?) takes the person's settings as LocalProfileOptions:
localMcp (off by default), localSkills (on by default), vision (the person's word on pictures) and languageStore.
The machine policy narrows them.
The endpoint¶
A ModelEndpoint has:
| Field | Meaning |
|---|---|
baseUrl |
The base, with /v1: http://localhost:11434/v1. It has no query, fragment, user name or password. |
model |
The model's id on that server. ChatOptions.model overrides it per request. |
key |
A TokenProvider that gives the key when a request needs it. The SDK never stores a key. |
dialect |
What the server expects where servers differ. The default is EndpointDialect.openAiCompatible. |
allowPlainHttpInLan |
The person's opt-in for plain http to the local network (see below). |
timeoutMs, streamIdleTimeoutMs |
How long a request may take, and how long a stream may send nothing. Both default to 5 minutes. |
fetch, logger |
Your own fetch (tests, a proxy) and a logger. The logger sees the method, route, status and duration, never content or the key. |
Dialects. A EndpointDialect says how a request is written: the length field (max_tokens or
max_completion_tokens), the thinking switch, whether a stream asks for usage figures, the header for the key
(Authorization: Bearer or api-key), and how the server's text watermark is asked for or switched off. Built in:
openAiCompatible, openAi, azureOpenAi, ollama, lmStudio, vllm, sglang, llamaCpp, liteLlm, openRouter
and mistral. EndpointDialect.named(name) finds one; a dialect is a plain object, so { ...EndpointDialect.sglang,
requestWatermark: false } makes a variant.
Presets. An EndpointPreset is a ready-made endpoint: an id, the usual base, the dialect, and whether it needs a key
(EndpointPreset.all, EndpointPreset.named(id)).
The check¶
new EndpointCheck(endpoint).run(options) finds out what the endpoint can do and returns an EndpointReport. It asks the
endpoint's own origin and nowhere else:
/models: is it reachable, is the key accepted, which models are listed, and does the chosen one exist.- A one-token streamed chat: does it answer, and does the stream carry usage figures.
- A tool probe: does the model call a tool. If not,
report.chatOnlyis true and the agent can only talk. - A picture probe, when
probeVisionis set: the model has to name the colour of a small green picture. A model that says what it takes in, through/models, is not asked. - The context length: the person's own (
contextLength), else what the server says it runs with. - The text watermark status, from a table of what each kind of server is documented to do.
The report keeps what it found: reachable, keyAccepted, models, chat, usage, toolCalls, vision,
contextLength, watermark and a list of problems the app can say in plain words (Unreachable, KeyRejected,
NotCompatible, ModelNotFound, NoToolCalls, ContextTooShort and others). report.usable says that the agent can be
used. toJson() and EndpointReport.fromJson(json) keep it with the connection; the JSON is the .NET SDK's.
EndpointCheck.placeOf(url) says where an address points: thisComputer, localNetwork or internet. A browser cannot
resolve names, so only the spelling decides. There is no search for local servers: a page may not scan ports, so the check
covers the one address it is given.
Text watermark status¶
report.watermark says whether text from this server carries the server's own mark: Marks, IfAccountEnabled,
IfOperatorConfigured, Never or Unknown, with the source the status rests on and the date it was read. Where a server
has a per-request switch, the dialect asks for the mark on text people read and switches it off only for calls no person
reads. agent.endpointWatermark gives the status for the agent in force, and EndpointCheck.watermarkOf(endpoint) gives
it with no request. The records the provenance package signs cite it.
Keys¶
- The key goes into the app's own key store, never into settings, logs or the address. The wizard's
EndpointKeyStorekeeps it under a WebCrypto key and gives back aTokenProvider. - The SDK asks the provider for the key at each request. A 401 is tried once more if the provider gives a different key.
- A key goes over plain http only to this computer (
localhost,127.0.0.1,[::1]). The check reports it asKeyUnencryptedOnThisComputer. A machine policy withplainHttp: forbiddenrefuses even that.
Transport rules¶
Every request follows these rules before anything is sent (OWASP ASVS 5.0 V12, V13):
- https goes anywhere. Plain http goes to this computer, and to the local network only after the person's opt-in for
this endpoint (
allowPlainHttpInLan) and never with a key. - A browser does not resolve names. The host's spelling decides: a number in a private range (10/8, 172.16/12,
192.168/16, link-local, fc00::/7), a single-label name, or a name ending in
.local,.lan,.home.arpaor.internalcounts as the local network. A name that only looks local can point anywhere, which is why https stays the way beyond this computer. The .NET SDK resolves the name instead. - A refusal is typed.
EndpointPlainHttpRefusedErrorhas areason:notLocal,noOptIn,keyOverPlainHttporforbiddenByPolicy. - No redirect leaves the origin. Requests are sent with
redirect: "manual"and without cookies. Where the address is visible (Node), a redirect to the same origin is followed, at most three times; any other is refused. A browser hides where a redirect points, so none is followed and the error has the coderedirect. - Errors are typed:
EndpointKeyRejectedError,EndpointOriginRefusedError(a local server that admits only some origins, as Ollama does withOLLAMA_ORIGINS),EndpointModelNotFoundError,EndpointContextLengthError,EndpointNotCompatibleError(usually a wrong base: it includes/v1),EndpointUnreachableError,ServerCertificateError(Node only: a browser cannot tell an untrusted certificate from an unreachable server) andEndpointPlainHttpRefusedError. A 429 is aFadenstackRateLimitedError. - Answers are capped. A body read whole is at most 32 MiB of text.
What is different from governed mode¶
- The agent reads its definition from the app, not its profile from a server. There is no server to report to, no grants and no organisation's tools or rules.
- The chats and the person's approvals are kept under the standalone principal, apart from any governed person's (Data on the device).
- In 0.3.0 the SDK offers no picture tools in standalone mode (Pictures and web search).
- Content marking uses the device's own signing, where the app adds
@fadenstack/provenance(Marking AI-generated content).