Getting Started

Crash Course

The core Agent OS Exec concepts in one page.

Agent OS Exec is the language-execution layer of AgentOS. The root package owns the VM and shell; /javascript and /python provide focused conveniences for running submitted source.

import { JavaScriptRuntime } from "@rivet-dev/agentos/javascript";

const javascript = await JavaScriptRuntime.create({
	cwd: "/workspace",
	env: { GREETING: "hello from the VM" },
});

try {
	const execution = await javascript.execute(`
		console.log(process.env.GREETING);
		console.error("stderr is captured separately");
	`);
	console.log(execution);

	const evaluation = await javascript.evaluate<{ sum: number; cwd: string }>(
		`({ sum: 2 + 40, cwd: process.cwd() })`,
	);
	console.log(evaluation);

	const typed = await javascript.typescript.evaluate<number>(
		`Promise.resolve(21 * 2 satisfies number)`,
	);
	console.log(typed);
} finally {
	await javascript.dispose();
}

import { PythonRuntime } from "@rivet-dev/agentos/python";


const python = await PythonRuntime.create({
	cwd: "/workspace",
	env: { GREETING: "hello from the VM" },
});

try {
	const execution = await python.execute(`
import os
import sys

print(os.environ["GREETING"])
print("stderr is captured separately", file=sys.stderr)
	`);
	console.log(execution);

	const evaluation = await python.evaluate<{ sum: number; cwd: string }>(
		`{"sum": 2 + 40, "cwd": __import__("os").getcwd()}`,
	);
	console.log(evaluation);
} finally {
	await python.dispose();
}

The important boundaries are:

One runtime owns one isolated VM and may launch many fresh processes.
Submitted code and payloads are untrusted; the sidecar/runtime enforces the filesystem, process, network, permissions, and resource policy.
execute() returns streams and an exit code; evaluate() adds a structured JSON value or guest error.
spawn() returns a live process for servers and interactive programs.
TypeScript tools are part of the JavaScript runtime and compile inside its VM.
The underlying runtime.vm exposes files, mounts, shell, HTTP requests, bindings, software, and other general AgentOS operations.

Continue with Executing Code, Node.js, or Python.