@leg3ndy/sandbox-runtime

Native command sandbox runtime for Otto Code.

This package wraps shell commands with platform sandboxing primitives so a host application can run command-line tools with explicit filesystem and network limits.

Installation

npm install @leg3ndy/sandbox-runtime

Platform Support

• macOS: uses the built-in sandbox-exec runtime.
• Linux: uses bubblewrap (bwrap).
• WSL: WSL2 only.
• Windows: not supported by this runtime.

Linux users need bubblewrap installed:

sudo apt install bubblewrap

Quick Start

import { SandboxManager } from '@leg3ndy/sandbox-runtime'

await SandboxManager.initialize({
  network: {
    allowedDomains: [],
    deniedDomains: [],
  },
  filesystem: {
    denyRead: [],
    allowRead: [],
    allowWrite: ['.'],
    denyWrite: ['.otto/settings.json'],
  },
})

const wrapped = await SandboxManager.wrapWithSandbox('npm test', '/bin/sh')
console.log(wrapped)

The returned command can be executed by the host process with its normal shell execution layer.

Configuration

type SandboxRuntimeConfig = {
  network: {
    allowedDomains: string[]
    deniedDomains: string[]
    allowLocalBinding?: boolean
    allowUnixSockets?: string[]
    allowAllUnixSockets?: boolean
  }
  filesystem: {
    denyRead: string[]
    allowRead?: string[]
    allowWrite: string[]
    denyWrite: string[]
    allowGitConfig?: boolean
  }
  ignoreViolations?: Record<string, string[]>
  ripgrep?: {
    command: string
    args?: string[]
    argv0?: string
  }
}

Diagnostics

const result = SandboxManager.checkDependencies()

if (result.errors.length > 0) {
  console.error(result.errors)
}

Security Notes

The runtime is intentionally conservative:

• unsupported platforms fail closed
• missing sandbox dependencies are reported before execution
• filesystem writes are allowlisted
• sensitive host paths can be denied even inside writable regions

Linux network domain filtering is not part of the 0.1.0 runtime. When network restriction is requested on Linux, the runtime uses network isolation instead of a domain-filtering proxy. Provider-agnostic domain filtering will be added in a future release.

License

UNLICENSED. Copyright LEG3NDY.