@nebutra/sandbox-runtime

Public mirror for @nebutra/sandbox-runtime from Nebutra/Nebutra-Sailor.

This repository is generated from the Nebutra Sailor monorepo. Package releases are cut from the monorepo and mirrored here for discovery, standalone cloning, and contribution intake.

• Canonical source: packages/ai/sandbox-runtime in Nebutra/Nebutra-Sailor
• Package registry: npm and GitHub Packages
• Contributions: open issues or PRs here; maintainers port accepted changes back into the monorepo source package

---

Unified sandbox runtime router for local and remote execution providers.

This package defines the domain-neutral sandbox contract used by Nebutra execution packages. It routes requests to configured providers, exposes provider health checks, and records debug events for execution troubleshooting.

Installation

pnpm add @nebutra/sandbox-runtime

Usage

import { SandboxRuntime } from "@nebutra/sandbox-runtime";

const runtime = SandboxRuntime.fromConfig();

const result = await runtime.exec({
  cmd: "echo sandbox ok",
  tenantId: "org_123",
  threadId: "thread_123",
  hints: {
    networkAccess: false,
    needsGpu: false,
  },
});

Providers

Default providers:

Provider	Behavior
local_mac	Calls the local sandbox service at SANDBOX_RUNTIME_LOCAL_URL or http://127.0.0.1:8020/api/v1/sandbox/exec
remote_code	Placeholder provider gated by SANDBOX_REMOTE_CODE_TOKEN
remote_gpu	Placeholder provider gated by SANDBOX_REMOTE_GPU_TOKEN
remote_workspace	Placeholder provider gated by SANDBOX_REMOTE_WORKSPACE_TOKEN

Remote placeholders intentionally throw until a provider SDK is configured by the host application.

Routing

const runtime = SandboxRuntime.fromConfig({
  routes: [
    { when: { needsGpu: true }, provider: "remote_gpu" },
    { when: { durationS: 30 }, provider: "remote_code" },
    { when: { needsGpu: false }, provider: "local_mac" },
  ],
});

const plan = runtime.plan({ cmd: "pnpm test", hints: { needsGpu: false } });

The first matching static route wins. If no route matches, the runtime falls back to local_mac when it is configured.

API

Export	Description
SandboxRuntime	Provider registry, planner, executor, and doctor
createLocalMacSandbox()	Local sandbox-service adapter
createRemotePlaceholder(id, envKey)	Explicit placeholder for remote providers
sandboxDebugPath()	Debug path helper
readSandboxDebug(limit)	Read sandbox debug events
ExecRequest / ExecResponse	Execution request and response contracts
Sandbox / SandboxHealth	Provider interface and health shape

License

MIT