Agents

Flue

Run Flue agents on Rivet with agentOS sandboxes.

This integration is in beta. APIs may change between releases.

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:

By default, Rivet stores actor state on the local file system.

To scale Rivet in production, follow a guide to deploy to your hosting provider of choice:

Rivet Compute

Vercel

Railway

Kubernetes

AWS ECS

Google Cloud Run

Hetzner

VM & Bare Metal

Custom Platform

Runtime model

Each Flue agent instance and workflow run has its own Rivet Actor and SQLite database. Direct prompts and dispatch() inputs use the same durable admission path, so accepted work can recover after interruption.

Normal agent and workflow requests return their 202 receipt after persisting the admission, its canonical input event, and a recovery alarm. Rivet then owns the turn as background work through c.keepAwake(...); the caller does not remain attached while the model or workflow runs. Workflow requests with ?wait=result are the explicit exception and stay open until the result is available.

The agentOS adapter derives a stable VM actor key from the Flue context ID. Reusing a context reconnects to the same durable /workspace filesystem.

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

Configuration

rivet() accepts an optional actors module path, defaulting to ./actors.ts. That module must export a registry created with setup(); the target adds its generated actors to that registry.

agentOSSandbox() accepts:

Option	Required	Description
`actor`	Yes	agentOS actor name from the registry, such as `vm`.
`registry`	Yes	The same application registry exported from `actors.ts`.
`params`	No	Parameters passed when connecting to a new agentOS actor.
`cwd`	No	Sandbox working directory. Defaults to `/workspace`.
`client`	No	Existing client configured for the same registry.

Read the agentOS + Flue documentation →