Runtime

Executing Code

Execute programs, evaluate values, and manage live processes with Agent OS Exec.

JavaScriptRuntime and PythonRuntime share the same small execution model. Each call starts a fresh guest process while keeping the runtime’s VM state.

// Boot a fully virtualized runtime. Guest code runs inside the kernel
// isolation boundary - no host escapes.
const runtime = await JavaScriptRuntime.create();

try {
	// evaluate() returns a JSON-serializable value and captures stdout/stderr.
	const result = await runtime.evaluate<{ message: string; sum: number }>(`
		(() => {
			console.log("hello from Agent OS Exec");
			return { message: "hello from Agent OS Exec", sum: 1 + 2 };
		})()
	`);

	if (!result.success) throw new Error(result.error.message);
	console.log("stdout:", JSON.stringify(result.stdout.trim()));
	console.log("value:", result.value);
	console.log("exitCode:", result.exitCode);
} finally {
	// Tear down the VM and release the sidecar.
	await runtime.dispose();
}

const runtime = await PythonRuntime.create();

try {
	const result = await runtime.evaluate<number>("21 * 2");
	console.log(result.success ? result.value : result.error);
} finally {
	await runtime.dispose();
}

execute() returns captured output and an exit code.
evaluate<T>() additionally returns a JSON-serializable value or guest error.
spawn() returns a live process with stdin, signals, and wait().
executeFile() runs an existing VM file; Python also has executeModule().

All modes accept cwd, env, argv, stdin, timeoutMs, an AbortSignal, and output callbacks. The underlying lifecycle and signal behavior is the same as AgentOS Processes & Shell.