Security Model

Understand agentOS trust boundaries, VM isolation, and host responsibilities.

agentOS runs untrusted guest code on behalf of a trusted host application. Each VM has a kernel-owned filesystem, process table, socket table, pipes, PTYs, permission policy, and language runtimes. Guest JavaScript executes in V8; WASM and Python use their managed executors. Guest operations reach the host only through the sidecar’s policy-enforcing interfaces.

Trust boundary

The security boundary is sidecar/runtime to executor. A guest bypassing an applied permission, mount boundary, egress rule, or resource limit is in scope. A trusted host deliberately choosing a permissive configuration or unsafe credential is not a runtime escape.

Host capabilities

Core runs inside the trusted application process, so the host may explicitly give a VM access to host resources: host functions, host-backed mounts, external sandboxes, and local software paths. Each of these runs with the host’s privileges. Expose them deliberately, and never pass guest-controlled values into their configuration.

If your application lets untrusted users configure VMs, accept only serializable configuration from them and resolve it against your own allowlist of mounts and software sources.

Hosted VM restrictions

The hosted agentOS actor accepts only serializable configuration. Its filesystem descriptors are resolved through a fixed registry, and software installation accepts only remote HTTPS .aospkg sources. It cannot receive:

• a host filesystem path or host-directory mount;
• a host function callback, closure, or arbitrary host object;
• a custom filesystem or software resolver;
• an unregistered actor implementation or lifecycle hook.

Use scoped JWTs to give an untrusted client access to exactly one hosted VM.

Isolation guarantees

• Guest processes are kernel-managed and never become host processes.
• Guest sockets pass through the kernel socket table and applied network policy.
• Trusted VM setup can update mounts and command stubs without relaxing guest filesystem permissions, including while a VM is running.
• Each VM’s filesystem, process table, and runtime state are isolated from other VMs.
• Host-backed embedded mounts are confined to the configured root on every operation, including symlink and .. resolution.
• Resource limits bound process count, descriptors, sockets, filesystem bytes, runtime memory, CPU time, queues, payloads, and waits.
• Limit pressure is logged or emitted as a structured warning; exhaustion fails with a typed error naming the limit and how to raise it.

Deny by default

Network access and host capabilities require explicit policy. Filesystem and guest process capabilities operate only within the VM-owned namespace. A scope can be "allow", "deny", or a rule set that matches the operation and target.

import { AgentOs, type Permissions } from "@rivet-dev/agentos-core";

// Core accepts the kernel permission tree plus policies for trusted host
// bindings and mounts.
const permissions = {
	network: {
		default: "deny",
		rules: [
			{
				mode: "allow",
				operations: ["*"],
				patterns: ["dns://api.example.com", "tcp://api.example.com:*"],
			},
		],
	},
} satisfies Permissions;

const vm = await AgentOs.create({ permissions });

await vm.dispose();

Operator responsibilities

• Authenticate and authorize users before they can reach a VM.
• Keep object-store credentials and package-download settings out of configuration that guest code or untrusted users can read.
• Choose permissions and resource limits for the workload.
• Treat software URLs and config as trusted control-plane input, while treating the downloaded bytes and executed code as hostile.
• Harden the host/container that runs the trusted sidecar.
• Prefer a distinct VM identity for mutually untrusted tenants.

See Permissions, Resource Limits, and Filesystem for the public configuration surfaces.