Configure the handler

createNimbusHandler is the Worker entry point. Its options set the auth mode, the remote API, your own routes, and the session hooks.

import { createNimbusHandler } from '@nimbus-sh/sdk/worker';

export default createNimbusHandler({
  auth: { mode: 'enforce' },                    // 'auto' | 'enforce' | 'legacy'
  sdk: { remote: true, config: nimbusConfig },  // the HTTP API Nimbus.connect talks to
  routes: myRoutes,                             // runs before the Nimbus router
  hooks: { onSessionStart },                    // first WebSocket upgrade per session
});

All four options are optional. createNimbusHandler({}) serves the terminal UI with auto-detected auth. The entry module must re-export NimbusSession and the RPC classes because wrangler resolves them by name. create-nimbus-app writes that block; keep it.

auth.mode protects /new and /s/<id>/. auto enforces auth when JWT_SECRET is set. enforce fails closed without it. legacy never verifies; the URL is the auth. In enforce mode, /new needs a session:create Bearer token and uses the attach exchange.

sdk.remote mounts /api/nimbus/v1/sandboxes/<id>/rpc. It is off by default. Nimbus ships no token-mint endpoint. Use routes to add one behind your own user auth.

routes: async (request, env) => {
  const url = new URL(request.url);
  if (url.pathname === '/api/auth/nimbus-token' && request.method === 'POST') {
    const user = await authenticateYourUser(request, env);
    return Response.json({
      token: await issueNimbusToken(env, { tn: 'acme', sub: user.id, scopes: ['session:create', 'session:attach'] }),
    });
  }
  return null; // fall through to Nimbus
},

The wrangler config

buildNimbusWranglerConfig emits the DO binding and migration, the LOADER binding, three R2 buckets, static assets, nodejs_compat, and the required bundler aliases. Use NIMBUS_REQUIRED_ALIASES when keeping the config by hand.

import { buildNimbusWranglerConfig } from '@nimbus-sh/config';

const config = buildNimbusWranglerConfig({
  name: 'my-nimbus-worker',
  runtimeCache: 'byoa',   // 'shared' (default) or bring-your-own-artifacts
  agent: { model: '@cf/moonshotai/kimi-k2.6', gatewayId: 'default' },
});

The CLI

@nimbus-sh/cli uses long flags and never prompts.

Command	Needs	Does
nimbus setup cloudflare --name <worker>	CLOUDFLARE_ACCOUNT_ID	Creates R2 buckets, seeds runtimes
nimbus token mint --tenant <t> [--scopes a,b --sid <id> --ttl <sec>]	JWT_SECRET	Prints a JWT
nimbus token verify <token>	JWT_SECRET	Prints the claims
nimbus session new	--endpoint/--token, or NIMBUS_ENDPOINT/NIMBUS_TOKEN as fallbacks	POSTs /new, prints the session id
nimbus runtime sync [--bucket <name>] <runtime[@ver]…>	CLOUDFLARE_ACCOUNT_ID	Stages runtime blobs (BYOA)
nimbus runtime list	—	Shows staged runtimes

With runtimeCache: 'shared', Nimbus creates and seeds the standard bucket. 'byoa' binds ${prefix}-runtime-cache. Stage its blobs with runtime sync. mintToken, syncRuntimes, setupCloudflare, and scaffold are also callable from code.