Embed Nimbus in a Worker

Deploy Nimbus to your own Cloudflare account, then create sandboxes from your Worker or from a React page.

npx create-nimbus-app my-nimbus-worker && cd my-nimbus-worker && npm install
CLOUDFLARE_ACCOUNT_ID=<account-id> npx @nimbus-sh/cli setup cloudflare --name my-nimbus-worker
npx wrangler secret put JWT_SECRET
npx wrangler deploy

setup cloudflare creates the R2 buckets and seeds the Python, Ruby, and clang runtimes. If Wrangler reports R2 error 10042, enable R2 once in that account’s dashboard and rerun. The Worker wraps createNimbusHandler from @nimbus-sh/sdk/worker, and configure the handler lists its options.

Use the SDK through a colocated DO binding, or connect to an authenticated deployment.

import { Nimbus } from '@nimbus-sh/sdk';
import { defineNimbusConfig } from '@nimbus-sh/config';

const config = defineNimbusConfig({
  sandboxes: {
    default: {
      root: '/home/user',
      runtimes: { preinstall: ['python'], onDemand: true, allow: ['node', 'npm', 'git', 'python', 'shell'] },
    },
  },
});

const box = Nimbus.fromEnv(env, config).sandbox('job-123', { tenant: 'acme', subject: 'agent' });
// or: Nimbus.connect({ endpoint, token, config }).sandbox('job-123')
const result = await box.exec('python -c "print(2 + 2)"');

The sandbox profile is a policy boundary. Nimbus enforces runtimes.allow and the preinstall and on-demand flags before any RPC. box.tools({ namespace: 'sandbox' }) is a Proteus-style tool provider. @nimbus-sh/sdk/flue adapts it to Flue’s sandbox contract.

From React

@nimbus-sh/react puts the session shell in an iframe. This keeps the page’s JavaScript away from the terminal’s WebSocket.

import { NimbusTerminal } from '@nimbus-sh/react';

<NimbusTerminal endpoint="https://my-nimbus.workers.dev" token={jwt} tenant="acme" sub="alice"
  onReady={() => console.log('attached')} style={{ height: 500 }} />

useNimbusSession gives the same flow without the component. It returns { sessionId, ready, error, attachUrl } from the shell’s nimbus:ready / nimbus:error postMessages, for building the iframe directly.

Nimbus is a Worker/DO/WASM sandbox, not a Linux VM. Capabilities & limits lists the boundaries. The hosted demo uses apps/hosted-demo, the same embedder shape an external project can ship.