Skip to main content

Documentation Index

Fetch the complete documentation index at: https://secureexec.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Example on GitHub

Runnable example for network access control.
Network access is deny-by-default. Enable it by setting useDefaultNetwork: true on the system driver and granting the network permission.

​
Runnable example

import * as http from "node:http";
import {
	NodeRuntime,
	allowAllNetwork,
	createDefaultNetworkAdapter,
	createNodeDriver,
	createNodeRuntimeDriverFactory,
} from "../../../packages/secure-exec/src/index.ts";

const logs: string[] = [];
const server = http.createServer((_req, res) => {
	res.writeHead(200, { "content-type": "text/plain" });
	res.end("network-ok");
});

await new Promise<void>((resolve, reject) => {
	server.once("error", reject);
	server.listen(0, "127.0.0.1", () => resolve());
});

const address = server.address();
if (!address || typeof address === "string") {
	throw new Error("missing loopback address");
}

const runtime = new NodeRuntime({
	systemDriver: createNodeDriver({
		networkAdapter: createDefaultNetworkAdapter({
			initialExemptPorts: [address.port],
		}),
		permissions: { ...allowAllNetwork },
	}),
	runtimeDriverFactory: createNodeRuntimeDriverFactory(),
});

try {
	const result = await runtime.exec(
		`
			(async () => {
				const response = await fetch("http://127.0.0.1:${address.port}/");
				const body = await response.text();

				if (!response.ok || response.status !== 200 || body !== "network-ok") {
					throw new Error(
						"unexpected response: " + response.status + " " + body,
					);
				}

				console.log(JSON.stringify({ status: response.status, body }));
			})().catch((error) => {
				console.error(error instanceof Error ? error.message : String(error));
				process.exitCode = 1;
			});
		`,
		{
			onStdio: (event) => {
				logs.push(`[${event.channel}] ${event.message}`);
			},
		},
	);

	if (result.code !== 0) {
		throw new Error(`Unexpected execution result: ${JSON.stringify(result)}`);
	}

	const payload = logs
		.filter((line) => line.startsWith("[stdout] "))
		.map((line) => line.slice("[stdout] ".length))
		.map((line) => JSON.parse(line))
		.at(-1);

	if (payload?.status !== 200 || payload?.body !== "network-ok") {
		throw new Error(`Unexpected captured output: ${JSON.stringify(logs)}`);
	}

	console.log(
		JSON.stringify({
			ok: true,
			status: payload.status,
			body: payload.body,
			summary: "sandbox fetched a host-managed loopback HTTP server",
		}),
	);
} finally {
	runtime.dispose();
	await new Promise<void>((resolve, reject) => {
		server.close((error) => {
			if (error) reject(error);
			else resolve();
		});
	});
}
Source: examples/features/src/networking.ts

​
Quick setup

import { createNodeDriver, allowAllNetwork } from "secure-exec";

const driver = createNodeDriver({
  useDefaultNetwork: true,
  permissions: { ...allowAllNetwork },
});
The Node adapter supports fetch, DNS lookups, and low-level HTTP requests.

​
Network adapters

You can provide a custom adapter instead of using useDefaultNetwork: 
import { createNodeDriver, createDefaultNetworkAdapter, allowAllNetwork } from "secure-exec";

const driver = createNodeDriver({
  networkAdapter: createDefaultNetworkAdapter(),
  permissions: { ...allowAllNetwork },
});
FactoryEnvironmentCapabilities
createDefaultNetworkAdapter()Nodefetch, DNS, HTTP
createBrowserNetworkAdapter()Browserfetch only

​
NetworkAdapter interface

MethodReturnsDescription
fetch(url, options?)Promise<FetchResponse>HTTP fetch
dnsLookup(hostname)Promise<DnsResult>DNS resolution
httpRequest(url, options?)Promise<HttpResponse>Low-level HTTP request

​
Loopback RPC exemptions

The default network adapter blocks all loopback/private-IP requests as SSRF protection. To allow sandbox code to call a host-side RPC server on specific loopback ports, use loopbackExemptPorts: 
import { createNodeDriver, allowAllNetwork } from "secure-exec";

const driver = createNodeDriver({
  useDefaultNetwork: true,
  loopbackExemptPorts: [rpcPort],
  permissions: { ...allowAllNetwork },
});
Only the listed ports are exempt — all other loopback and private-IP requests remain blocked. If you need more control (e.g. dynamic port discovery), construct the adapter directly: 
import { createNodeDriver, createDefaultNetworkAdapter, allowAllNetwork } from "secure-exec";

const driver = createNodeDriver({
  networkAdapter: createDefaultNetworkAdapter({
    initialExemptPorts: [rpcPort],
  }),
  permissions: { ...allowAllNetwork },
});

​
Permission gating

Use a function to filter requests: 
const driver = createNodeDriver({
  useDefaultNetwork: true,
  permissions: {
    network: (req) => {
      if (req.hostname?.endsWith(".internal")) {
        return { allow: false };
      }
      if (req.hostname === "169.254.169.254") {
        return { allow: false };
      }
      return { allow: true };
    },
  },
});