SDK installation

Install

npm install @poolot/lily-web

The package is ESM and ships TypeScript types. Import the same way in the browser and on Node:

import { createLilyAgent } from '@poolot/lily-web'

The package's exports map resolves automatically to the browser build or the Node build depending on your environment, so you don't choose a bundle by hand.

Keep it out of server-side rendering

In the browser, the agent runs from a WebAssembly engine that must not load during SSR. In frameworks that render on the server, import the SDK lazily on the client:

// Runs only in the browser
const { createLilyAgent } = await import('@poolot/lily-web')
const agent = await createLilyAgent({ apiKey })

Serving the engine's assets (browser)

By default the browser build loads its engine files from your own bundle, and falls back to a pinned CDN version if they aren't found. To serve them yourself (recommended for production), copy the assets into your public folder with the bundled script:

npx lily-web-copy-assets

Then point the SDK at them with the assetBase option:

const agent = await createLilyAgent({ apiKey, assetBase: '/lily' })

Content-Security-Policy (browser)

Running WebAssembly and the agent's tools requires a few CSP directives. If your app sets a CSP, include:

script-src  'self' 'unsafe-eval' 'wasm-unsafe-eval' https://cdn.jsdelivr.net;
connect-src 'self' https://agent.pathvela.com https://cdn.jsdelivr.net;
worker-src  'self' blob:;
frame-src   'self';
img-src     'self' data: https:;
  • wasm-unsafe-eval is required to instantiate the WebAssembly engine.
  • connect-src must allow the Pathvela backend (https://agent.pathvela.com) and, if you rely on the CDN fallback, cdn.jsdelivr.net.
  • worker-src and frame-src support sandboxed tools.

Serve your app over HTTPS or localhost — WebAssembly needs a secure context.

Node harness (optional)

On Node, a native harness unlocks the full tool set. It isn't bundled (it's large). Install it during your build, or let the SDK download it on demand:

npx lily-web-install-harness

const agent = await createLilyAgent({ apiKey, autoDownload: true })

Without a harness, the SDK falls back to the WebAssembly engine — see Browser vs Node.

Next