Frameworks

Flue

Use agentOS as the durable sandbox backend for Flue.

Flue owns the agent runtime and session lifecycle. Rivet maps each agent instance and workflow run to a durable Rivet Actor, while agentOS gives each Flue context an isolated VM with a persistent /workspace filesystem.

View the complete example →

Quickstart

Create a Flue project

mkdir my-agent && cd my-agent
npm init -y
npm pkg set type=module

# Install the Flue packages
npm add "@flue/runtime@npm:@rivet-dev/labs-flue-runtime@1.0.0-beta.9-rivet.2"
npm add --save-dev "@flue/cli@npm:@rivet-dev/labs-flue-cli@1.0.0-beta.9-rivet.2"

# Install the Rivet packages
npm add @rivet-dev/flue @rivet-dev/agentos @rivet-dev/agentos-flue rivetkit

# Initialize the project
npx flue init --target node

@flue/cli and @flue/runtime: Build and run the Flue project using Rivet’s preview Flue packages.
@rivet-dev/flue: Runs Flue agents and workflows as Rivet Actors.
@rivet-dev/agentos and @rivet-dev/agentos-flue: Provide the agentOS VM and connect Flue’s sandbox API to it.

This uses Rivet’s Flue fork. We’re working to merge its extension APIs upstream so Flue can support actor-model runtimes without a Rivet fork.

Register agentOS with the Rivet target

Create actors.ts:

import { agentOS, setup } from "@rivet-dev/agentos";

const vm = agentOS({
	// Configure software, permissions, mounts, and resource limits here.
});

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

Update flue.config.ts:

import { defineConfig } from "@flue/cli/config";
import { rivet } from "@rivet-dev/flue";

export default defineConfig({
	target: rivet(),
});

Use agentOS as the Flue sandbox

Create agents/assistant.ts:

import { createAgent } from "@flue/runtime";
import { agentOSSandbox } from "@rivet-dev/agentos-flue";
import { registry } from "../actors.js";

export default createAgent(() => ({
	model: "anthropic/claude-sonnet-5",
	sandbox: agentOSSandbox({ actor: "vm", registry }),
}));

Run Flue

Set the provider key required by your model, such as ANTHROPIC_API_KEY, in .env.

Run the agent:

npx flue run assistant --id local \
  --input '{"message":"Write hello from Flue to /workspace/hello.txt, run wc -c /workspace/hello.txt, then read the file back."}'

Deploy

Deploy to one of the supported platforms:

Runtime model

agentOS does not support Cloudflare Workers yet. It works with Node.js, Bun, or Deno on platforms such as Railway, Kubernetes, or Vercel.

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.

Flue sandbox

agentOSSandbox() accepts:

Option	Required	Description
`actor`	Yes	Actor registered with `setup()`, such as `vm`.
`registry`	Yes	The application registry exported from `actors.ts`.
`cwd`	No	Base directory exposed to Flue. Defaults to `/workspace`.
`params`	No	Connection parameters forwarded to the actor’s `onBeforeConnect` hook.
`client`	No	An existing client configured for the same registry.