Skip to content

Hosting

This page covers where an application runs the SDK, a web page, a browser extension or Node, and what differs between them. The .NET SDK's page of this name covers registering an agent with the standard host and its service container; the TypeScript SDK has no container, so this page covers the places the code runs instead.

The packages are ES modules and use standard web APIs only: fetch, Web Streams, Web Crypto and AbortSignal, plus IndexedDB in a browser. They run in Chrome 116 or later and in Node.js 24 or later.

What is the same everywhere

  • You build the agent the same way: a FadenstackClient, a builder, tools, an approval handler. See Build an agent.
  • The client never sends the browser's cookies, so another sign-in in the same browser never acts in place of your application's.
  • The client refuses an http:// address unless you set allowInsecureHttp.
  • Event reporting, the policy checks and the transcript format are the same.

What differs

Web page Browser extension Node
Sessions and "Allow always" IndexedDB, encrypted with a non-extractable key per signed-in user The same, in the extension's pages and service worker Memory only: nothing is written, no key is made
The sign-in Memory by default; pass a TokenStore to keep it Memory by default; a store over chrome.storage keeps it (see In a browser extension) Memory by default; a store over a file only the user can read keeps it
Preferences (language, the unmarked notice) Yours to pass; browserPreferences() keeps them in localStorage, as fadenstack.<name>:<tenant>:<user> per person Yours to pass: chrome.storage, or browserPreferences() (localStorage where there is one, else memory) Yours to pass; MemoryPreferenceStore keeps them in memory
Opening the second sign-in or the pairing page openInBrowser: a new tab, never an iframe Give your own handler (a tab of the extension) Give your own handler
The chat panel @fadenstack/ui-react or ui-vue The same, in a page of the extension Not applicable: the skins draw DOM
Logging Your logger, or consoleLogger The same The same

A web page

Create the client with FadenstackClient.forAgent, build the agent, and put the panel in the page. The default stores are the signed-in user's own IndexedDB databases, so two people in one browser profile never see each other's chats. Script that runs in your origin can ask the SDK for the sessions; see Sessions on the device for what that protects, and Data on the device for every database. The default token store keeps the sign-in in memory, so the person signs in again on the next load; pass a TokenStore to keep it longer.

openInBrowser(link) opens a page in a new window or tab with no opener and returns false when the browser blocked it. browserStepUp() is a step-up handler built on it, for the second sign-in that Bypass needs. See Server-held grants and Bypass.

A browser extension

An extension uses the same packages in its service worker and its pages. It needs a place for the sign-in that outlives the page: a TokenStore over chrome.storage.local, or chrome.storage.session for a sign-in per browser session. The example is in Build an agent. An extension signs in by pairing, since it cannot ask for a password the way a login page does: see Sign in by pairing.

The chat view model takes the host's clipboard, link opener, download and preferences store, with no default (see The host's services). An extension opens links its own way: pass openLink over browserChatServices(), and set openBrowser on the ApprovalBroker, so a second sign-in opens in a tab of the extension and not in a window the page opens.

Node

Node has no IndexedDB, so the default session and approval stores are MemorySessionStore and MemoryApprovalStore: the conversation lasts as long as the process, and the SDK writes nothing to disk and keeps no key. A service that must keep conversations passes its own SessionStore and ApprovalStore and, to encrypt them, a SecretProtector over its own key store (see Encryption). Because the stores are the host's, deleteMyData reports hostStoresLeft and leaves them to you.

The sign-in is kept in memory unless you pass a TokenStore; a file that only the user can read is the usual choice. @fadenstack/testing runs a fake server in the same process, and FakeGateway.listen serves it over HTTP on 127.0.0.1 for a process that needs a URL.

What the TypeScript SDK does not have

  • No dependency injection. There is no AddFadenstackAgent. Create the agent where your application starts and pass it to what needs it.
  • No local MCP servers. A browser cannot start a process. Tools that should be on request are host tools; see Local tools.
  • No file sink for logs. The SDK hands its log entries to the logger you give it; see Logging.
  • No OS key store. Browsers get a WebCrypto key; a host that wants more supplies a SecretProtector.