torbox

Isolated sandbox executor with optional Tor SOCKS5 routing.
Zero runtime dependencies — uses bubblewrap or firejail available on the host.

Install

# System deps (one of)
sudo apt install bubblewrap   # recommended
sudo apt install firejail

# Optional: Tor
sudo apt install tor && sudo systemctl start tor

# Module
npm install torbox

Quick start

import { Sandbox } from "torbox";

// Basic sandbox — no Tor
const sb = new Sandbox();

const result = await sb.run({
  lang: "python3",
  code: `
import os, socket
print("hostname:", socket.gethostname())
print("user:", os.getenv("USER", "none"))
  `,
});

console.log(result.stdout);
// hostname: sandbox
// user: none

// With Tor routing
const tor = new Sandbox({
  tor: { host: "127.0.0.1", port: 9050 },
});

const check = await tor.run({
  lang: "python3",
  code: `
import urllib.request, json
res = urllib.request.urlopen("https://check.torproject.org/api/ip", timeout=15)
print(json.load(res))
  `,
});

console.log(check.stdout); // { IP: "...", IsTor: true }

API

new Sandbox(opts?)

Option	Type	Default	Description
backend	"bwrap" | "firejail" | "auto"	"auto"	Isolation backend
tor	TorOptions	—	Enables Tor routing
tor.host	string	"127.0.0.1"	SOCKS5 host
tor.port	number	9050	SOCKS5 port
tor.verify	boolean	true	Check Tor is reachable on init
fs.roBind	Array<{host, guest}>	[]	Extra read-only bind mounts
fs.rwBind	Array<{host, guest}>	[]	Extra read-write bind mounts
timeout	number	30000	Max execution time (ms)
env	Record<string,string>	{}	Extra env vars
cwd	string	"/tmp"	Working dir inside sandbox

sandbox.run(opts): Promise<ExecResult>

Option	Type	Description
lang	"node" | "python3" | "bash" | "sh"	Interpreter
code	string	Script source
stdin	string	Optional stdin
env	Record<string,string>	Per-run env override
timeout	number	Per-run timeout override

Returns ExecResult:

{
  exitCode: number;
  stdout: string;
  stderr: string;
  durationMs: number;
  backend: "bwrap" | "firejail";
  torEnabled: boolean;
}

sandbox.probe(): Promise<{ backend, binPath }>

Resolves config and returns the active backend without executing anything.

sandbox.checkTor(): Promise<void>

Verifies Tor SOCKS5 is reachable. Throws if not.

Isolation model

bubblewrap (bwrap) — recommended

• New user, PID, UTS, IPC namespaces
• Read-only bind of /usr, /lib, /bin, /sbin
• tmpfs on /tmp and /home
• Network namespace not isolated by default (needed for 127.0.0.1:9050)
• seccomp via bwrap defaults

firejail

• All capabilities dropped
• seccomp default profile
• Private /tmp
• No new privileges

Tor routing

When tor is set, the sandbox receives:

ALL_PROXY=socks5h://127.0.0.1:9050
HTTPS_PROXY=socks5h://127.0.0.1:9050
HTTP_PROXY=socks5h://127.0.0.1:9050

socks5h:// — the h means DNS is also resolved through Tor (no local DNS leaks).

Advanced: full network isolation with veth pair

For complete network isolation (sandbox can only reach Tor, nothing else), see the veth POC.

Limitations

• Linux only (namespaces are a Linux kernel feature)
• The process running the sandbox needs permission to use bwrap (usually fine on modern distros)
• Tor must be started separately (systemctl start tor)
• No Node.js vm module isolation — this is OS-level, not JS-level