WebAssembly

Run the fx agent in the browser with your own interface, or use the fx terminal. Both run through WebAssembly.

For a complete HTML page and server route, start with the browser example. On Node.js, use the native SDK.

npm install libfx@0.0.17

Check runtime support

The WebAssembly build needs JavaScript Promise Integration (JSPI). Call supportsJspi() before you create the agent, so you can show an unsupported-browser message instead of failing during startup. In Node.js 24, enable JSPI with --experimental-wasm-jspi; the native Node agent doesn't need it.

Run a headless agent

In a browser project with a bundler, this example asks for a key and streams a reply to the console:

import { createFxAgent, supportsJspi } from 'libfx/browser'

if (!supportsJspi()) {
  throw new Error('fx requires JSPI support')
}

const agent = createFxAgent({ apiKey: window.prompt('AI Gateway API key') ?? undefined })

const turn = agent.session().prompt('Explain closures in two sentences.')
for await (const event of turn) {
  if (event.type === 'text_delta') console.log(event.delta)
}
const { stopReason, usage } = await turn.result
console.log(stopReason, usage)

A browser has no environment variables, so pass apiKey. The key entered here goes directly to AI Gateway. Keep a shared application key on the server and proxy requests through your backend, as the browser example does.

By default, a browser agent keeps its sessions in the page's memory, and they end with the page. To keep a browser conversation, save its checkpoint, or run the agent on your server and stream it to the page.

Import the factories you use from libfx/browser. Importing it does no work until you create an agent or a terminal, so a client component that a server renders can import it. Agent and terminal code are separate: an agent or engine loads fx-core.wasm and a terminal loads fx-term.wasm, and the browser entry point resolves each one relative to the installed package.

Bundlers copy these files differently. Next.js copies only the files your client code uses into the build. Vite 8 copies both unless you set build.rolldownOptions.experimental.lazyBarrel to true, though a browser still downloads only the file your app uses. esbuild copies neither. If your bundler doesn't serve the file you need, copy it to a public asset directory and pass its URL as wasm.

If a CDN serves the .wasm files, for example through Next.js's assetPrefix, it must send Content-Type: application/wasm so the browser can compile while it downloads. Otherwise libfx downloads the whole file before compiling it. When the files come from a different origin than the page, the response also needs CORS headers, such as Access-Control-Allow-Origin, or the browser blocks the request.

Save conversations and add tools

Use checkpoints to save and restore a conversation. Add JavaScript tools, MCP tools, and skills when you create the agent.

An embedded agent doesn't inherit the CLI's shell, filesystem, or stored credentials. Its tools run in your application and have only the access you give them.

WebAssembly runtime limits

WebAssembly can't start native processes or reach a native keychain or filesystem. Tool calls run one after another. Each agent has its own memory and conversations. When agents reuse the same source URL or object, the SDK compiles the module once.

Embed the terminal

createFxTerminal() runs the fx terminal using fx-term.wasm. It handles prompts and output through a terminal interface instead of a UI you build around agent events.

Follow the web terminal guide to connect xterm.js, save sessions, and add login and workspace adapters.