Getting started

Install

npm install @verklet/sdk
# or
pnpm add @verklet/sdk
# or
yarn add @verklet/sdk

The SDK is published as ESM-only. It expects a browser environment with SharedArrayBuffer available — see browser support for the cross-origin isolation headers your page needs to serve.

Boot a runtime

import { Runtime } from '@verklet/sdk';

const runtime = await Runtime.boot({
  projectId: 'prj_demo',
  persistenceKey: 'my-first-runtime',
});

Runtime.boot() spins up the coordinator worker, sets up the virtual filesystem, and resolves once everything is ready. projectId is a public identifier used to load compatible hosted runtime assets, choose the package registry, and report usage; it is safe to ship in browser code. With a persistenceKey, the filesystem state is hydrated from OPFS if the visitor has been here before.

Mount some files

await runtime.mount({
  '/workdir': {
    'package.json': { contents: '{"type":"module"}' },
    'index.mjs': { contents: 'console.log("hello from a tab")' },
  },
});

The mount API takes a tree object. Files contain contents; directories contain nested entries. You can mount as many trees as you like; later mounts overlay earlier ones.

Spawn a process

const proc = await runtime.spawn('node', ['index.mjs'], {
  cwd: '/workdir',
});

for await (const chunk of proc.output) {
  console.log(chunk);
}

await proc.exit;

spawn returns a process handle with an async-iterable output stream, an exit promise that resolves with the exit code, and stdin/kill methods for interactive control.

Listen for server-ready events

If your spawned process opens a port, Verklet emits a server-ready event you can use to fetch from it or open it in an iframe:

runtime.on('server-ready', async ({ port, url }) => {
  console.log(`server is up on :${port}`);
  // `url` is a service-worker-routed URL on this origin.
  iframeRef.current.src = url;
});

Tear down

await runtime.teardown();

Call this on unmount to release worker handles and free resources. If persistOnTeardown was set, the filesystem is flushed to OPFS first.