Skip to main content
Frameworks

Vercel Eve

Run Vercel Eve with agentOS and Rivet World.

Eve owns the agent runtime and session lifecycle. agentOS maps every sandbox session to an isolated VM actor with a durable /workspace filesystem, while Rivet World runs Eve workflows on Rivet Actors.

View the complete example →

Quickstart

Create an Eve agent

npx eve@latest init my-agent
cd my-agent

Install the integrations

npm add @rivet-dev/agentos @rivet-dev/agentos-eve @rivet-dev/vercel-world
  • @rivet-dev/agentos: Provides the agentOS VM.
  • @rivet-dev/agentos-eve: Connects Eve’s sandbox API to agentOS.
  • @rivet-dev/vercel-world: Runs Eve workflows on Rivet World.

Set up the Eve agent

Update agent/agent.ts:

import { defineAgent } from "eve";

export default defineAgent({
	model: "anthropic/claude-sonnet-5",
	build: {
		externalDependencies: [
			"@rivet-dev/agentos",
			"@rivet-dev/agentos-core",
			"@rivet-dev/agentos-eve",
			"@rivet-dev/agentos-runtime-core",
			"@rivet-dev/agentos-sidecar",
			"@rivet-dev/vercel-world",
			"@rivetkit/engine-cli",
		],
	},
	experimental: {
		workflow: { world: "#world" },
	},
});

Configure Rivet World

Rivet World lets you run Eve on top of Rivet.

Add the World module import to package.json:

{
	"imports": {
		"#world": "./world.ts"
	}
}

Create world.ts:

import { createWorld as createRivetWorld } from "@rivet-dev/vercel-world";
import { registry } from "./registry";

export const createWorld = () => createRivetWorld({ registry });

The first World operation starts this registry and waits for the Rivet envoy to be ready.

Configure agentOS

Create registry.ts:

import { agentOS, setup } from "@rivet-dev/agentos";
import { vercelWorldActors } from "@rivet-dev/vercel-world/registry";

const vm = agentOS({
	// Configuration will go here.
});

export const registry = setup({
	use: {
		...vercelWorldActors,
		vm,
	},
});

Create agent/sandbox.ts:

import { agentOSBackend } from "@rivet-dev/agentos-eve";
import { defineSandbox } from "eve/sandbox";
import { registry } from "../registry";

export default defineSandbox({
	backend: agentOSBackend({ actor: "vm", registry }),
});

Run Eve

Install the Vercel CLI, then link Eve once so it can call your configured model:

npm install --global vercel@latest
npm exec -- eve link

Then run the agent:

npm exec -- eve dev

Default Filesystem

agentOS persists the VM filesystem, including /workspace, to Rivet Actor storage by default. Additional mounts can be configured as needed.

Configuration

Virtual Machine

See the agentOS() configuration reference to configure the VM.

Eve Sandbox Backend

agentOSBackend() accepts:

OptionRequiredDescription
actorYesActor registered with setup(), such as vm.
registryYesThe application registry containing that actor. It is started lazily and shared by Eve sessions.
clientNoAn existing client configured for the same registry.

Rivet World

Rivet World stores Eve workflow runs in Rivet Actors so they resume instead of restarting.

Read the Rivet World documentation →

Advanced

agentOS Core Backend

Use agentOSCoreBackend() when Eve should create agentOS Core VMs directly without Rivet Actor orchestration. The create callback owns the complete VM configuration:

pnpm add @rivet-dev/agentos-core

import { AgentOs } from "@rivet-dev/agentos-core";
import { agentOSCoreBackend } from "@rivet-dev/agentos-eve";
import { defineSandbox } from "eve/sandbox";

export default defineSandbox({
	backend: agentOSCoreBackend({
		create: ({ sessionKey }) =>
			AgentOs.create({
				mounts: [
					{
						path: "/workspace",
						plugin: {
							id: "host_dir",
							config: {
								hostPath: `/var/lib/eve/${encodeURIComponent(sessionKey)}`,
							},
						},
						readOnly: false,
					},
				],
			}),
	}),
});

When using agentOS Core instead of regular agentOS, you lose:

  • Durable filesystem and session history. Core’s root filesystem is ephemeral by default, so you must provide your own persistent mount at /workspace.
  • Stable per-session actor identity. Core cannot reconnect to the same VM across Eve process restarts.
  • Automatic sleep and wake. The VM lives inside Eve’s short-lived server process instead staying awake for a given grace period. shutdown() disposes it.

Use Core only when your application owns equivalent persistence and lifecycle management.

Edit this page