nebula-ai-core 0.1.0

package/src/runtime/runtime.ts

@@ -0,0 +1,113 @@
+import { mkdir } from 'node:fs/promises'
+import type { Brain } from '../brain/types'
+import type { NebulaConfig } from '../config'
+import { EventQueue, listeners, newEventId, routeLoop } from '../events'
+import type { NebulaEvent } from '../events/types'
+import type { IdentityProvider } from '../identity/types'
+import { addEntryLine, readIndexFile, writeIndexFile } from '../memory/index-file'
+import { agentPaths } from '../paths'
+import type { Storage } from '../storage/types'
+import { ToolRegistry } from '../tools/registry'
+import { type ActivityEntry, ActivityLog } from './activity'
+
+export interface RuntimeDeps {
+  config: NebulaConfig
+  identity: IdentityProvider
+  brain: Brain
+  storage: Storage
+}
+
+export class Runtime {
+  readonly queue: EventQueue
+  readonly tools: ToolRegistry
+  private activity?: ActivityLog
+  private running = false
+  private routeTask?: Promise<void>
+
+  constructor(private readonly deps: RuntimeDeps) {
+    this.queue = new EventQueue()
+    this.tools = new ToolRegistry(deps.config.tools)
+  }
+
+  /** Ensure per-agent filesystem exists and boot the event loop. */
+  async start(): Promise<void> {
+    if (this.running) return
+    const id = (await this.deps.identity.current()).agentId
+    const paths = agentPaths.agent(id)
+
+    await mkdir(paths.memoryDir, { recursive: true })
+    await mkdir(paths.agentMemoryDir, { recursive: true })
+    await mkdir(paths.userMemoryDir, { recursive: true })
+    await mkdir(paths.publicDir, { recursive: true })
+    await mkdir(paths.cache, { recursive: true })
+
+    this.activity = new ActivityLog(paths.activityLog)
+
+    // Initialize MEMORY.md if missing.
+    let index = await readIndexFile(paths.memoryIndex)
+    if (index.lines.length === 0) {
+      index = {
+        lines: [
+          `# ${id} — Memory Index`,
+          '',
+          'Self-contained memory for this agent. Topic files live under `agent/` (transfers with iNFT) and `user/` (purges on transfer).',
+          '',
+          '## Memories',
+          '',
+        ],
+        entries: new Map(),
+      }
+      index = addEntryLine(index, {
+        file: 'agent/identity.md',
+        title: 'Agent identity',
+        hook: 'Seed record of this agent — tokenId, creation block, operator history.',
+      })
+      await writeIndexFile(paths.memoryIndex, index)
+    }
+
+    this.routeTask = routeLoop(this.queue, {
+      brain: this.deps.brain,
+      tools: this.tools,
+      onTurn: async (ev, turn) => {
+        await this.activity?.append({
+          ts: Date.now(),
+          kind: 'brain-response',
+          data: {
+            event: { id: ev.id, source: ev.source },
+            content: turn.content,
+            toolCalls: turn.toolCalls,
+            finishReason: turn.finishReason,
+            usage: turn.usage,
+          },
+        })
+      },
+    })
+    this.running = true
+
+    await listeners.startAll(this.queue)
+  }
+
+  /** Push an event onto the queue from outside the listener system. */
+  async fire(event: Omit<NebulaEvent, 'id' | 'ts'>): Promise<string> {
+    const ev: NebulaEvent = { ...event, id: newEventId(), ts: Date.now() }
+    await this.activity?.append({
+      ts: ev.ts,
+      kind: 'wake',
+      data: { id: ev.id, source: ev.source, label: ev.payload.label },
+    })
+    this.queue.enqueue(ev)
+    return ev.id
+  }
+
+  async logActivity(entry: ActivityEntry): Promise<void> {
+    await this.activity?.append(entry)
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) return
+    this.running = false
+    this.queue.close()
+    await listeners.stopAll()
+    await this.routeTask
+  }
+}

package/src/sandbox/credentials.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared credential-dir blocklist used by every sandbox backend (macOS
+ * seatbelt, Linux bubblewrap). Centralized so the platforms don't drift —
+ * earlier the bwrap profile included `~/.config/anthropic` + `~/.gnupg`
+ * while the seatbelt profile didn't. Centralizing closes that gap.
+ */
+
+/**
+ * Cross-platform credential paths to blackhole. Relative to homedir; backends
+ * format the absolute path. `Library/Keychains` is macOS-only but keeping it
+ * here is harmless on Linux (the path won't exist; `--tmpfs` no-ops).
+ */
+export const CREDENTIAL_DIR_RELATIVE_PATHS: readonly string[] = [
+  '.ssh',
+  '.aws',
+  'Library/Keychains',
+  '.config/gcloud',
+  '.config/anthropic', // claude-code config
+  '.gnupg',
+] as const
+
+/** Build the absolute paths of credential dirs to deny under `homedir`. */
+export function credentialDirs(homedir: string): string[] {
+  return CREDENTIAL_DIR_RELATIVE_PATHS.map(rel => `${homedir}/${rel}`)
+}

package/src/sandbox/docker.ts

@@ -0,0 +1,396 @@
+/**
+ * Container sandbox backend (Tier 3, Phase 9.5 follow-up to sandbox-exec).
+ *
+ * Works with EITHER Docker Desktop OR Podman — they provide the same CLI.
+ * Auto-detects the runtime; same default config works for both. Operator
+ * can force a specific binary via `runtimePath` opt.
+ *
+ * Same isolation shape as hermes-agent's `TERMINAL_ENV=docker` mode (full Linux
+ * container). Differences from Tier 2 (sandbox-exec):
+ *
+ *  - Container has its own filesystem (chroot-like). Host fs invisible to the
+ *    sandboxed processes unless explicitly mounted via `mountWorkspace=true`.
+ *  - Container has its own /tmp, /etc, /home — `rm -rf /tmp/*` only nukes the
+ *    container's tmpdir, never the host's.
+ *  - Network goes through the runtime's bridge by default (still allowed for
+ *    nebula's RPC/storage/compute/WC traffic to escape the container).
+ *  - Cold-start cost ~1s on the FIRST tool call after nebula boot (longer if
+ *    the image is being pulled). Subsequent `exec` calls are ~50-100ms.
+ *
+ * Hybrid MVP: only shell.run / shell.process_start / code.execute go through
+ * the container. fs.* tools still run on host (gated by PathGuard). browser.*
+ * still runs on host. A future bundle would re-exec all of nebula inside the
+ * container; this is the lower-risk incremental step.
+ *
+ * Lifecycle:
+ *  - `wrapSpawn` lazy-starts the container on first call.
+ *  - Container runs `nikolaik/python-nodejs:python3.11-nodejs20` by default
+ *    (matches hermes' default; has bash, python3, node, npm, git, curl on
+ *    standard PATH).
+ *  - Container is detached (`run -d`), idle-loops on `tail -f /dev/null` so it
+ *    stays alive between exec calls.
+ *  - `dispose()` kills the container. chat.tsx wires this to process exit
+ *    handlers.
+ *
+ * Failure modes:
+ *  - Runtime not installed → constructor throws clear error; factory falls
+ *    back to LocalBackend with stderr warning.
+ *  - Daemon/machine not running → first call surfaces "daemon unreachable"
+ *    error from the runtime. With podman on macOS, requires `podman machine
+ *    start` once.
+ *  - Image pull on first run → 30-60s, surfaced as "starting container" log.
+ *  - Container crash mid-session (external `podman kill`, OOM, daemon
+ *    restart) → wrapSpawn detects the stale cache via a fast
+ *    `podman inspect --format '{{.State.Running}}'` probe and self-heals by
+ *    invalidating containerId + re-running startContainer. Cost: one extra
+ *    inspect (~5-15ms on the warm Podman API socket) per shell-class call.
+ *    Worth the latency vs. the alternative of leaving the brain stuck on
+ *    "no such container" errors with no recovery path.
+ */
+
+import { type SpawnOptions, execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { promisify } from 'node:util'
+import type {
+  SandboxBackend,
+  SandboxBackendOpts,
+  SandboxEnvHint,
+  SandboxSpawnRequest,
+  WrappedSpawn,
+} from './types'
+
+const exec = promisify(execFile)
+
+/**
+ * Probe order for container runtime auto-detect. First existing path wins.
+ * macOS Homebrew Podman lives at /opt/homebrew/bin/podman; Docker Desktop
+ * symlinks /usr/local/bin/docker to its CLI (or to podman, on machines
+ * with both). Linux paths included for completeness.
+ */
+const RUNTIME_CANDIDATES: ReadonlyArray<{ path: string; runtime: 'docker' | 'podman' }> = [
+  { path: '/usr/local/bin/docker', runtime: 'docker' },
+  { path: '/opt/homebrew/bin/docker', runtime: 'docker' },
+  { path: '/opt/homebrew/bin/podman', runtime: 'podman' },
+  { path: '/usr/bin/docker', runtime: 'docker' },
+  { path: '/usr/bin/podman', runtime: 'podman' },
+]
+
+interface RuntimeInfo {
+  path: string
+  runtime: 'docker' | 'podman'
+}
+
+function detectRuntime(override?: string): RuntimeInfo {
+  if (override) {
+    if (!existsSync(override)) {
+      throw new Error(`container runtime override path does not exist: ${override}`)
+    }
+    const runtime = override.includes('podman') ? 'podman' : 'docker'
+    return { path: override, runtime }
+  }
+  for (const cand of RUNTIME_CANDIDATES) {
+    if (existsSync(cand.path)) return cand
+  }
+  throw new Error(
+    'no container runtime found. Install Docker Desktop or Podman (`brew install podman`) and ensure the daemon/machine is running.',
+  )
+}
+
+export interface DockerBackendOpts extends SandboxBackendOpts {
+  /**
+   * Container image. Default: `nikolaik/python-nodejs:python3.11-nodejs20`
+   * (matches hermes-agent's TERMINAL_DOCKER_IMAGE default; has bash, python3,
+   * node, npm, git, curl on standard PATH so every code.execute language and
+   * shell tool works out of the box). Switch to `oven/bun:1` (~250MB vs 700MB)
+   * if you only need bun/ts and don't care about python.
+   */
+  image?: string
+  /**
+   * Mount the host's workspaceRoot into the container at /workspace. Default
+   * `false` for max isolation (container has no view of host fs). Set true
+   * when the operator wants the agent to read/edit host project files.
+   */
+  mountWorkspace?: boolean
+  /**
+   * Override container runtime binary path. Default: auto-detect (docker, then
+   * podman). Set this to force one or the other, e.g. `/opt/homebrew/bin/podman`.
+   */
+  runtimePath?: string
+  /** Override container start timeout in ms. Default 60000 (60s for image pull). */
+  startTimeoutMs?: number
+  /**
+   * CPU cores cap (passed to runtime as `--cpus`). Float (e.g. 0.5, 2). Unset =
+   * unlimited (runtime default). Hermes default is 1; nebula leaves UNSET so
+   * the container competes fairly with host work unless the operator opts in.
+   */
+  cpu?: number
+  /**
+   * Memory cap in MB (`--memory <N>m`). Unset = unlimited. Hermes default is
+   * 5120 (5GB). OOM kills happen at this cap, so prefer leaving it unset
+   * unless the operator wants a hard guard against runaway pip installs.
+   */
+  memoryMb?: number
+  /**
+   * Per-container disk cap in MB (`--storage-opt size=<N>m`). Linux + overlay2
+   * with pquota only — silently dropped on macOS (Docker Desktop / podman
+   * machine). Unset = unlimited.
+   */
+  diskMb?: number
+  /**
+   * Block all network access from inside the container (`--network=none`).
+   * Default false (container's bridge network reaches the internet). Useful
+   * for max-paranoia code.execute runs that should never reach out.
+   */
+  noNetwork?: boolean
+}
+
+/**
+ * Always-on hardening flags ported from hermes-agent's `_SECURITY_ARGS`. Drop
+ * every Linux capability then re-add the minimum needed by package managers
+ * (pip / npm / apt set ownership and override DAC), block setuid escalation,
+ * cap process count to stop fork bombs, and replace tmpfs /tmp /var/tmp /run
+ * with size-limited writable tmpfs that doesn't bleed into the host. `--init`
+ * gives the container a real PID 1 (tini) that reaps zombies — without it,
+ * background tools that orphan children leak file descriptors.
+ */
+const HARDENING_ARGS: ReadonlyArray<string> = [
+  '--init',
+  '--cap-drop',
+  'ALL',
+  '--cap-add',
+  'DAC_OVERRIDE',
+  '--cap-add',
+  'CHOWN',
+  '--cap-add',
+  'FOWNER',
+  '--security-opt',
+  'no-new-privileges',
+  '--pids-limit',
+  '256',
+  '--tmpfs',
+  '/tmp:rw,nosuid,size=512m',
+  '--tmpfs',
+  '/var/tmp:rw,noexec,nosuid,size=256m',
+  '--tmpfs',
+  '/run:rw,noexec,nosuid,size=64m',
+]
+
+export class DockerBackend implements SandboxBackend {
+  readonly mode = 'docker' as const
+  readonly label: string
+  private readonly image: string
+  private readonly mountWorkspace: boolean
+  private readonly runtime: RuntimeInfo
+  private readonly startTimeoutMs: number
+  private readonly workspaceRoot: string
+  private readonly cpu?: number
+  private readonly memoryMb?: number
+  private readonly diskMb?: number
+  private readonly noNetwork: boolean
+  private containerId: string | null = null
+  private starting: Promise<string> | null = null
+  /**
+   * Last `Date.now()` at which `isContainerAlive` returned true. Used to
+   * cache the result and skip the ~30-70ms `inspect` probe when the container
+   * was confirmed alive recently. The window is narrow enough that a stale
+   * cache only delays self-heal by ALIVE_PROBE_TTL_MS in the rare case where
+   * the container died externally.
+   */
+  private lastAliveProbeMs = 0
+  private static readonly ALIVE_PROBE_TTL_MS = 30_000
+
+  constructor(opts: DockerBackendOpts) {
+    this.image = opts.image ?? 'nikolaik/python-nodejs:python3.11-nodejs20'
+    this.mountWorkspace = opts.mountWorkspace ?? false
+    this.runtime = detectRuntime(opts.runtimePath)
+    this.startTimeoutMs = opts.startTimeoutMs ?? 60_000
+    this.workspaceRoot = opts.workspaceRoot
+    this.cpu = opts.cpu
+    this.memoryMb = opts.memoryMb
+    this.diskMb = opts.diskMb
+    this.noNetwork = opts.noNetwork ?? false
+    this.label = `${this.runtime.runtime}:${this.image}${this.mountWorkspace ? '+workspace' : ''}`
+  }
+
+  /**
+   * Lazy-starts the container on first call. Reuses on subsequent calls.
+   * Synchronous assignment to `this.starting` BEFORE the first await ensures
+   * concurrent first-callers all wait on the same Promise (otherwise each
+   * read `this.starting === null`, each kicked off `startContainer`, and only
+   * the last wrote — leaking N-1 orphan containers).
+   */
+  private ensureContainer(): Promise<string> {
+    if (this.containerId) return Promise.resolve(this.containerId)
+    if (this.starting) return this.starting
+    const promise = this.startContainer().then(
+      id => {
+        this.containerId = id
+        return id
+      },
+      err => {
+        this.starting = null
+        throw err
+      },
+    )
+    this.starting = promise
+    return promise
+  }
+
+  private async startContainer(): Promise<string> {
+    // Verify the runtime daemon/machine is reachable. Fast-fail with a clear
+    // error if not. Podman on macOS needs `podman machine start` once before
+    // the API responds.
+    try {
+      await exec(this.runtime.path, ['version', '--format', '{{.Server.Version}}'], {
+        timeout: 5_000,
+      })
+    } catch (err) {
+      const hint =
+        this.runtime.runtime === 'podman'
+          ? "Run `podman machine start` if you haven't yet."
+          : 'Start Docker Desktop.'
+      throw new Error(
+        `${this.runtime.runtime} daemon unreachable (${(err as Error).message}). ${hint} Or set sandbox.mode='os' / 'none'.`,
+      )
+    }
+
+    const runArgs: string[] = [
+      'run',
+      '-d',
+      '--rm',
+      '--label',
+      'nebula-sandbox=1',
+      ...HARDENING_ARGS,
+    ]
+    // Run as host UID so files created in a mounted workspace are owned by
+    // the host user. Podman rootless on macOS handles this automatically; we
+    // only force --user on docker/podman where the default would be root.
+    if (this.runtime.runtime === 'docker') {
+      runArgs.push('--user', `${process.getuid?.() ?? 0}:${process.getgid?.() ?? 0}`)
+    }
+    // Optional resource caps. `--cpus` and `--memory` work cross-platform.
+    // `--storage-opt size` only works on Linux + overlay2 with pquota; we
+    // skip it on darwin to match hermes' behavior (silently a no-op there).
+    if (this.cpu && this.cpu > 0) runArgs.push('--cpus', String(this.cpu))
+    if (this.memoryMb && this.memoryMb > 0) runArgs.push('--memory', `${this.memoryMb}m`)
+    if (this.diskMb && this.diskMb > 0 && process.platform !== 'darwin') {
+      runArgs.push('--storage-opt', `size=${this.diskMb}m`)
+    }
+    if (this.noNetwork) runArgs.push('--network=none')
+    if (this.mountWorkspace) {
+      runArgs.push('-v', `${this.workspaceRoot}:/workspace`)
+      runArgs.push('-w', '/workspace')
+    }
+    // Mount the host's tmpdir READ-ONLY at the same path inside the container
+    // so code.execute's host-written snippet (mkdtemp + writeFile happen on
+    // host, then `python3 <hostpath>` runs in container) is actually readable.
+    // RO so the container can't write back — the container's own /tmp stays
+    // isolated and `rm /var/folders/...` from inside fails with EROFS.
+    const hostTmp = tmpdir()
+    runArgs.push('-v', `${hostTmp}:${hostTmp}:ro`)
+    runArgs.push(this.image, 'tail', '-f', '/dev/null')
+
+    const { stdout } = await exec(this.runtime.path, runArgs, {
+      timeout: this.startTimeoutMs,
+    })
+    const containerId = stdout.toString().trim()
+    if (!containerId || containerId.length < 12) {
+      throw new Error(
+        `${this.runtime.runtime} run returned unexpected output: "${containerId.slice(0, 200)}"`,
+      )
+    }
+    return containerId
+  }
+
+  async wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn> {
+    let containerId = await this.ensureContainer()
+    // Self-heal stale cache: container may have died since last call (external
+    // `podman kill`, OOM, daemon restart, --rm cleanup after host crash).
+    // Probe is rate-limited to ALIVE_PROBE_TTL_MS so the happy path doesn't
+    // pay the ~30-70ms inspect tax on every spawn — only the first call after
+    // the TTL window pays. Worst case after external kill: one failed exec
+    // before the next probe re-spawns.
+    const now = Date.now()
+    if (now - this.lastAliveProbeMs > DockerBackend.ALIVE_PROBE_TTL_MS) {
+      if (!(await this.isContainerAlive(containerId))) {
+        this.containerId = null
+        this.starting = null
+        this.lastAliveProbeMs = 0
+        containerId = await this.ensureContainer()
+      }
+      this.lastAliveProbeMs = Date.now()
+    }
+    // `exec -i` (interactive stdin), preserve env subset, run inside the
+    // container. We pass env explicitly via `-e` rather than relying on
+    // container env so redactedEnv from the tool layer actually reaches the
+    // inner process.
+    const envArgs: string[] = []
+    if (req.options.env) {
+      for (const [k, v] of Object.entries(req.options.env)) {
+        if (typeof v === 'string') envArgs.push('-e', `${k}=${v}`)
+      }
+    }
+    const cwdArg: string[] = []
+    if (this.mountWorkspace && req.options.cwd === this.workspaceRoot) {
+      cwdArg.push('-w', '/workspace')
+    }
+    // Strip cwd + env from passed-through options because we redirected both
+    // into exec flags. Keep stdio/etc.
+    const {
+      cwd: _cwd,
+      env: _env,
+      ...passOptions
+    } = req.options as SpawnOptions & {
+      cwd?: unknown
+      env?: unknown
+    }
+    return {
+      command: this.runtime.path,
+      args: ['exec', '-i', ...envArgs, ...cwdArg, containerId, req.command, ...req.args],
+      options: passOptions,
+    }
+  }
+
+  /**
+   * Fast liveness probe. `inspect --format '{{.State.Running}}'` returns
+   * "true" / "false" when the container exists, fails non-zero when missing.
+   * 3s timeout prevents a wedged daemon from stalling every spawn.
+   */
+  private async isContainerAlive(id: string): Promise<boolean> {
+    try {
+      const { stdout } = await exec(
+        this.runtime.path,
+        ['inspect', '--format', '{{.State.Running}}', id],
+        { timeout: 3_000 },
+      )
+      return stdout.toString().trim() === 'true'
+    } catch {
+      return false
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (!this.containerId) return
+    const id = this.containerId
+    this.containerId = null
+    this.starting = null
+    this.lastAliveProbeMs = 0
+    try {
+      await exec(this.runtime.path, ['kill', id], { timeout: 5_000 })
+    } catch {
+      // Container may already be dead; --rm cleaned up. Best-effort.
+    }
+  }
+
+  envHint(): SandboxEnvHint {
+    return {
+      mode: 'docker',
+      label: this.label,
+      innerOs: 'linux',
+      workspaceMount: this.mountWorkspace ? '/workspace' : null,
+      scope:
+        'shell.run, code.execute, shell.process_start run inside the container; fs.*, browser.*, memory.* run on the host',
+    }
+  }
+}

package/src/sandbox/factory.ts

@@ -0,0 +1,99 @@
+/**
+ * Factory: build the right backend for the configured mode + current platform.
+ *
+ *   mode='none'   → LocalBackend (passthrough)
+ *   mode='os' on darwin → MacOSSandboxExecBackend (sandbox-exec wrapper)
+ *   mode='os' on linux  → LocalBackend + warning (bubblewrap impl pending)
+ *   mode='os' elsewhere → LocalBackend + warning
+ *   mode='docker' → throws "not yet implemented" (separate bundle)
+ *
+ * Failure mode: misconfiguration silently degrades to LocalBackend with a
+ * stderr warning rather than crashing init. Nebula MUST boot even on
+ * unsupported platforms; the sandbox is a defense-in-depth layer, not a hard
+ * requirement.
+ */
+
+import { DockerBackend } from './docker'
+import { LinuxBubblewrapBackend } from './linux'
+import { LocalBackend } from './local'
+import { MacOSSandboxExecBackend } from './macos'
+import type { SandboxBackend, SandboxBackendOpts, SandboxMode } from './types'
+
+export interface MakeSandboxOpts extends SandboxBackendOpts {
+  mode: SandboxMode
+  /** Override platform detection. Defaults to process.platform. Test hook. */
+  platform?: NodeJS.Platform
+  /** Sink for the platform-fallback warning. Defaults to process.stderr.write. */
+  warn?: (msg: string) => void
+  /** docker mode: container image override (default `nikolaik/python-nodejs:python3.11-nodejs20`). */
+  dockerImage?: string
+  /** docker mode: bind-mount workspaceRoot into container at /workspace (default false). */
+  dockerMountWorkspace?: boolean
+  /** docker mode: force a specific runtime binary path (auto-detect by default). */
+  dockerRuntimePath?: string
+  /** docker mode: CPU cores cap (`--cpus`). Unset = unlimited. */
+  dockerCpu?: number
+  /** docker mode: memory cap in MB (`--memory <N>m`). Unset = unlimited. */
+  dockerMemoryMb?: number
+  /** docker mode: per-container disk cap in MB. Linux+overlay2 only; ignored on darwin. */
+  dockerDiskMb?: number
+  /** docker mode: block all network from inside container (`--network=none`). Default false. */
+  dockerNoNetwork?: boolean
+}
+
+export function makeSandboxBackend(opts: MakeSandboxOpts): SandboxBackend {
+  const platform = opts.platform ?? process.platform
+  const warn = opts.warn ?? ((m: string) => process.stderr.write(m))
+
+  if (opts.mode === 'none') return new LocalBackend()
+
+  if (opts.mode === 'docker') {
+    try {
+      return new DockerBackend({
+        agentDir: opts.agentDir,
+        workspaceRoot: opts.workspaceRoot,
+        homedir: opts.homedir,
+        image: opts.dockerImage,
+        mountWorkspace: opts.dockerMountWorkspace,
+        runtimePath: opts.dockerRuntimePath,
+        cpu: opts.dockerCpu,
+        memoryMb: opts.dockerMemoryMb,
+        diskMb: opts.dockerDiskMb,
+        noNetwork: opts.dockerNoNetwork,
+      })
+    } catch (err) {
+      warn(
+        `nebula: docker sandbox failed to initialize, falling back to passthrough: ${(err as Error).message}\n`,
+      )
+      return new LocalBackend()
+    }
+  }
+
+  // mode === 'os'
+  if (platform === 'darwin') {
+    try {
+      return new MacOSSandboxExecBackend(opts)
+    } catch (err) {
+      warn(
+        `nebula: macOS sandbox-exec failed to initialize, falling back to passthrough: ${(err as Error).message}\n`,
+      )
+      return new LocalBackend()
+    }
+  }
+
+  if (platform === 'linux') {
+    try {
+      return new LinuxBubblewrapBackend(opts)
+    } catch (err) {
+      warn(
+        `nebula: linux bubblewrap sandbox failed to initialize, falling back to passthrough: ${(err as Error).message}\n`,
+      )
+      return new LocalBackend()
+    }
+  }
+
+  warn(
+    `nebula: sandbox.mode="os" not supported on platform "${platform}", falling back to passthrough\n`,
+  )
+  return new LocalBackend()
+}

package/src/sandbox/index.ts

@@ -0,0 +1,15 @@
+export { LocalBackend } from './local'
+export { MacOSSandboxExecBackend } from './macos'
+export { LinuxBubblewrapBackend, buildBwrapArgs } from './linux'
+export { DockerBackend, type DockerBackendOpts } from './docker'
+export { makeSandboxBackend, type MakeSandboxOpts } from './factory'
+export { buildSeatbeltProfile, type SeatbeltProfileOpts } from './seatbelt-profile'
+export type {
+  SandboxBackend,
+  SandboxBackendOpts,
+  SandboxEnvHint,
+  SandboxMode,
+  SandboxSpawnRequest,
+  WrappedSpawn,
+} from './types'
+export { credentialDirs, CREDENTIAL_DIR_RELATIVE_PATHS } from './credentials'