Quickstart

npm install secure-exec

import { evaluate } from "secure-exec";

// Each call runs in a fresh VM that is disposed when the call finishes.
const sum = await evaluate<number>("1 + 2");
console.log(sum.outcome === "succeeded" ? sum.value : sum.error); // 3

// `inputs` hands host values to the code as real objects, so data is never
// interpolated into source.
const total = await evaluate<number>(
	"inputs.prices.reduce((a, b) => a + b, 0)",
	{ inputs: { prices: [5, 10, 27] } },
);
console.log(total.outcome === "succeeded" ? total.value : total.error); // 42

// Inside the VM each collection is a global, and each function is async. This
// is the code a model would write.
const generated = `(async () => {
	const list = await orders.list({ customer: inputs.customer });
	return list.reduce((sum, order) => sum + order.amount, 0);
})()`;

// Host functions run in your process, with your credentials. The guest only
// sees their inputs and outputs. The keys name the collection and the function,
// and `execute` receives the input its own schema describes.
const total = await evaluate<number>(generated, {
	hostFunctions: {
		orders: {
			list: {
				inputSchema: z
					.object({ customer: z.string() })
					.describe("List a customer's orders."),
				execute: ({ customer }) => [
					{ customer, amount: 40 },
					{ customer, amount: 2 },
				],
			},
		},
	},
	inputs: { customer: "customer_123" },
	timeoutMs: 5_000,
	output: { capture: "stderr" },
});
console.log(total.outcome === "succeeded" ? total.value : total.stderr); // 42

// Guest errors are returned, not thrown. Capture stderr to see the stack.
const failed = await evaluate(`JSON.parse("not json")`, {
	output: { capture: "stderr" },
});
if (failed.outcome !== "succeeded") {
	console.log(failed.outcome, failed.stderr?.split("\n")[0]); // failed SyntaxError: ...
}