JuliusBrussee/caveman · error

cave_sandbox_os_network_isolation_unavailable

cave_sandbox_os_network_isolation_unavailable

Error message

cave_sandbox_os_network_isolation_unavailable

What it means

networkIsolatedNode builds an OS-level network-isolated child process (Node with --no-addons plus platform-specific sandboxing). When no supported OS sandbox mechanism is available, it throws this error because it cannot honestly promise network isolation. Raised inside networkIsolatedNode, reached via isolated().

Solutions

1. Run the agent on a supported OS/kernel that provides the sandbox primitive (Linux netns or macOS seatbelt)
2. Enable unprivileged user namespaces (sysctl kernel.unprivileged_userns_clone=1) or run with the capability needed for network namespaces
3. Use an alternative isolation boundary (container/VM) and skip OS-level network isolation
4. Upgrade Node so the execPath supports the required launch flags

Example fix

// before: assuming isolation everywhere
const child = await isolated(fn);
// after: probe support first
if (!await supportsNetworkIsolation()) {
  console.warn('network isolation unavailable; running without it');
  const child = await fn();
} else {
  const child = await isolated(fn);
}

function supportsOsNetworkIsolation(): boolean {
  return process.platform === 'linux' || process.platform === 'darwin';
}

try {
  child = await isolated(fn);
} catch (e) {
  if (e.message === 'cave_sandbox_os_network_isolation_unavailable') {
    child = await fn(); // run without isolation, log a warning
  } else throw e;
}

When it happens

Trigger: Requesting a network-isolated execution environment on an OS/configuration where the required sandboxing primitive (e.g. macOS sandbox-exec profiles or Linux network namespaces) is unavailable.

Common situations: Running on Windows or an unsupported Unix variant; container environments without CAP_SYS_ADMIN / unprivileged userns so network namespaces cannot be created; stripped-down Node builds missing needed flags.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• cave_sandbox_network_egress_unbounded
• cave_host_sandbox_nested_under_required
• cave_live_eval_sandbox_profile_escapes_root
• cave_sandbox_child_process_containment_unavailable
• cave_sandbox_conformance_failed

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/0025c9162da47bed. Report an issue: GitHub.

Appendix: source

Thrown at packages/agent/src/sandbox-network.ts:65

        ...nodeArgs,
      ],
    };
  }
  if (process.platform === "linux") {
    return {
      command: "/usr/bin/unshare",
      args: [
        "--user",
        "--map-root-user",
        "--net",
        "--",
        process.execPath,
        "--no-addons",
        ...nodeArgs,
      ],
    };
  }
  throw new Error("cave_sandbox_os_network_isolation_unavailable");
}

View on GitHub (pinned to 3ee70a1026)