# Vercel Eve

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 →](https://github.com/rivet-dev/agentos/tree/main/examples/vercel-eve)

## Quickstart

### Create an Eve agent

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

### Install the integrations

```sh
npm add @rivet-dev/agentos @rivet-dev/agentos-eve @rivet-dev/vercel-world
```

- `@rivet-dev/agentos` and `@rivet-dev/agentos-eve`: Provide the agentOS VM and connect Eve's sandbox API to it.
- `@rivet-dev/vercel-world`: Runs Eve workflows on [Rivet World](https://workflow-sdk.dev/worlds).

### Set up the Eve agent

Update `agent/agent.ts`:

agent/agent.ts:

```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`:

```json title="package.json"
{
	"imports": {
		"#world": "./world.ts"
	}
}
```

Create `world.ts`:

world.ts:

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

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

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

### Configure agentOS

Create `actors.ts`:

actors.ts:

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

const vm = agentOS();

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

Create `agent/sandbox.ts`:

agent/sandbox.ts:

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

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:

```sh
npm install --global vercel@latest
npx eve link
```

Then run the agent:

```sh
npx eve dev
```

### Deploy

By default, agentOS runs locally with `npx rivetkit dev` — no infrastructure needed. To run in production, deploy to any of these targets:

See [Deployment](/agentos/self-host) for managed, self-hosted, and agentOS Core options.

## 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](/agentos/docs/core#configuration-reference) to configure the VM.

### Eve Sandbox Backend

`agentOSBackend()` accepts:

| Option | Required | Description |
| --- | --- | --- |
| `actor` | Yes | Actor registered with `setup()`, such as `vm`. |
| `registry` | Yes | The application registry containing that actor. It is started lazily and shared by Eve sessions. |
| `client` | No | An 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 →](https://rivet.dev/docs/integrations/vercel-workflows)

## 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:

```sh
pnpm add @rivet-dev/agentos-core
```

core.ts:

```ts
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.