@@ -1278,6 +1597,7 @@ function BackendSetupRivet() {
function BackendSetup() {
const provider = useWatch({ name: "provider" });
+ const isAgentOs = useWatch({ name: "template" }) === "agent-os";
const mode = useWatch({ name: "mode" }) as
| "serverless"
| "serverfull"
@@ -1290,6 +1610,7 @@ function BackendSetup() {
return (
+ {isAgentOs ?
: null}
@@ -1477,6 +1798,7 @@ function FrontendSetup() {
});
const provider = useWatch({ name: "provider" });
+ const isAgentOs = useWatch({ name: "template" }) === "agent-os";
const nsDataProvider = useCloudNamespaceDataProvider();
const { namespace: namespaceParam } = useParams({ strict: false }) as { namespace: string };
const { data: nsData } = useQuery(
@@ -1545,15 +1867,31 @@ function FrontendSetup() {
/>
diff --git a/frontend/src/components/actors/dialogs/create-actor-sheet.tsx b/frontend/src/components/actors/dialogs/create-actor-sheet.tsx
index 2c2432302b..84494ffee4 100644
--- a/frontend/src/components/actors/dialogs/create-actor-sheet.tsx
+++ b/frontend/src/components/actors/dialogs/create-actor-sheet.tsx
@@ -22,9 +22,14 @@ import * as ActorCreateForm from "../form/actor-create-form";
interface CreateActorSheetProps {
open: boolean;
onOpenChange: (open: boolean) => void;
+ variant?: "actor" | "agent-os";
}
-export function CreateActorSheet({ open, onOpenChange }: CreateActorSheetProps) {
+export function CreateActorSheet({
+ open,
+ onOpenChange,
+ variant = "actor",
+}: CreateActorSheetProps) {
const { mutateAsync } = useMutation(
useDataProvider().createActorMutationOptions(),
);
@@ -35,6 +40,14 @@ export function CreateActorSheet({ open, onOpenChange }: CreateActorSheetProps)
const { copy } = useActorsView();
const [advancedOpen, setAdvancedOpen] = useState(false);
+ const isAgentOs = variant === "agent-os";
+ const title = isAgentOs
+ ? "Create agentOS instance"
+ : copy.createActorModal.title(name);
+ const description = isAgentOs
+ ? "agentOS boots an isolated VM for this key. Choose the agentOS build and a key to identify this instance."
+ : copy.createActorModal.description;
+
return (
-
- {copy.createActorModal.title(name)}
-
-
- {copy.createActorModal.description}
-
+ {title}
+ {description}
{/*
diff --git a/frontend/src/components/onboarding/agent-os/agent-os-onboarding.stories.tsx b/frontend/src/components/onboarding/agent-os/agent-os-onboarding.stories.tsx
new file mode 100644
index 0000000000..0a7b30310a
--- /dev/null
+++ b/frontend/src/components/onboarding/agent-os/agent-os-onboarding.stories.tsx
@@ -0,0 +1,99 @@
+import type { Story } from "@ladle/react";
+import { useState } from "react";
+import "../../../../.ladle/ladle.css";
+import { AgentSelect } from "./agent-select-step";
+import {
+ type AgentOsSelections,
+ buildAgentOsSetup,
+} from "./build-agent-os-setup";
+import { DEFAULT_AGENT, DEFAULT_PACKAGES } from "./catalog";
+import { SandboxMount, type SandboxValue } from "./sandbox-mount-step";
+import { SoftwareSelect } from "./software-select-step";
+
+// Integration story: the three agentOS selection steps wired to the pure
+// `buildAgentOsSetup` generator, so the generated install command / server.ts /
+// client.ts / handoff prompt update live as selections change. This is the unit
+// that matters (selection -> generated code); the individual card lists are
+// trivial on their own.
+function Harness({ initial }: { initial: AgentOsSelections }) {
+ const [agent, setAgent] = useState(initial.agent);
+ const [packages, setPackages] = useState(initial.packages);
+ const [sandbox, setSandbox] = useState(initial.sandbox);
+
+ const setup = buildAgentOsSetup({ agent, packages, sandbox });
+
+ return (
+
+
+
+
+
+ {setup.installCommand}
+
+
+
+
+
+
+
+
{title}
+ {children}
+
+ );
+}
+
+function Code({ children }: { children: string }) {
+ return (
+
+ {children}
+
+ );
+}
+
+export const Playground: Story = () => (
+
+ {AGENTS.map((agent) => (
+ onChange(agent.slug)}
+ />
+ ))}
+
+ );
+}
+
+// Wizard step: binds AgentSelect to the react-hook-form `agent` field.
+export function AgentSelectStep() {
+ const { field } = useController({ name: "agent" });
+ return (
+ ();
+
+// getOrCreate boots the agentOS instance on first call.
+const agent = client.vm.getOrCreate(["my-agent"]);
+
+agent.on("sessionEvent", (data) => console.log(data.event));
+
+const session = await agent.createSession("${agent.slug}", {
+ env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
+});
+await agent.sendPrompt(
+ session.sessionId,
+ "Write a hello world script to /home/user/hello.js",
+);
+
+const content = await agent.readFile("/home/user/hello.js");
+console.log(new TextDecoder().decode(content));
+`;
+
+ const prompt = buildPrompt({
+ agentTitle: agent.title,
+ softwareEntries,
+ sandboxEnabled,
+ provider,
+ installCommand,
+ serverCode,
+ clientCode,
+ });
+
+ return { installCommand, serverCode, clientCode, prompt };
+}
+
+function buildPrompt(opts: {
+ agentTitle: string;
+ softwareEntries: SoftwareEntry[];
+ sandboxEnabled: boolean;
+ provider: string;
+ installCommand: string;
+ serverCode: string;
+ clientCode: string;
+}): string {
+ const {
+ agentTitle,
+ softwareEntries,
+ sandboxEnabled,
+ provider,
+ installCommand,
+ serverCode,
+ clientCode,
+ } = opts;
+
+ const softwareList =
+ softwareEntries.length > 0
+ ? softwareEntries.map((s) => `- ${s.title} (${s.package})`).join("\n")
+ : "- (none beyond the agent)";
+
+ const sandboxSection = sandboxEnabled
+ ? `\n## Sandbox mounting
+
+This setup mounts a ${provider} sandbox at \`/sandbox\` for heavy workloads. It requires the \`sandbox-agent\` and \`@rivet-dev/agent-os-sandbox\` packages and a running ${provider} provider. See https://rivet.dev/docs/agent-os/sandbox.
+`
+ : "";
+
+ return `# agentOS Setup
+
+I want to add agentOS to this project using RivetKit. agentOS is a portable, open-source operating system for agents that runs in your process. Software is baked into the build at build time and is immutable after deploy, so these choices are made up front. An agentOS actor is a normal Rivet Actor and deploys like any other.
+
+Read https://rivet.dev/docs/agent-os/quickstart before making changes. agentOS is in preview.
+
+## Selections
+
+Agent: ${agentTitle}
+Software baked into the build:
+${softwareList}
+Sandbox mounting: ${sandboxEnabled ? `enabled (${provider})` : "disabled"}
+
+## Steps
+
+### Step 1: Install
+
+\`\`\`bash
+${installCommand}
+\`\`\`
+
+### Step 2: Create the server (server.ts)
+
+\`\`\`ts
+${serverCode}\`\`\`
+
+### Step 3: Configure the model key
+
+The agent needs an LLM key at runtime. Set \`ANTHROPIC_API_KEY\` in the environment locally, and once deployed, set it as a deployment secret. Never hardcode it.
+
+### Step 4: Boot an instance and run a prompt (client.ts)
+
+\`\`\`ts
+${clientCode}\`\`\`
+${sandboxSection}
+### Step 5: Verify
+
+Run the server, then the client, and confirm the agent created the file. Then verify it works through the Rivet inspector or your deployed endpoint.
+
+## If You Get Stuck
+
+agentOS is in preview. See https://rivet.dev/docs/agent-os, the troubleshooting guide at https://rivet.dev/docs/actors/troubleshooting, or the Rivet Discord (https://rivet.dev/discord).`;
+}
diff --git a/frontend/src/components/onboarding/agent-os/catalog.ts b/frontend/src/components/onboarding/agent-os/catalog.ts
new file mode 100644
index 0000000000..4069eff18b
--- /dev/null
+++ b/frontend/src/components/onboarding/agent-os/catalog.ts
@@ -0,0 +1,176 @@
+// Curated agentOS registry catalog for the onboarding selection steps.
+//
+// The canonical registry lives at website/src/data/registry.ts, but it is
+// website-only (the dashboard has no access to it). This is a curated subset of
+// the entries relevant to onboarding. A future unification into
+// frontend/packages/shared-data (where deploy.ts already lives) would remove the
+// drift; out of scope for now.
+
+export type CatalogStatus = "available" | "coming-soon";
+
+export interface AgentEntry {
+ slug: string;
+ title: string;
+ description: string;
+ status: CatalogStatus;
+ /** Present only when status is "available". */
+ package?: string;
+}
+
+export interface SoftwareEntry {
+ slug: string;
+ title: string;
+ package: string;
+ description: string;
+}
+
+export interface SandboxProviderEntry {
+ slug: string;
+ title: string;
+ description: string;
+ /**
+ * Only `docker` is verified against an in-repo example
+ * (examples/agent-os/src/sandbox/server.ts). Other providers follow the
+ * `sandbox-agent/` subpath + same-named factory pattern and should be
+ * confirmed before relying on the generated import.
+ */
+ verified?: boolean;
+}
+
+// Coding agents. Only Pi is available today; the rest render disabled.
+export const AGENTS: AgentEntry[] = [
+ {
+ slug: "pi",
+ title: "Pi",
+ description: "Lightweight, fast coding agent.",
+ status: "available",
+ package: "@rivet-dev/agent-os-pi",
+ },
+ {
+ slug: "claude-code",
+ title: "Claude Code",
+ description: "Coming soon.",
+ status: "coming-soon",
+ },
+ {
+ slug: "codex",
+ title: "Codex",
+ description: "Coming soon.",
+ status: "coming-soon",
+ },
+ {
+ slug: "amp",
+ title: "Amp",
+ description: "Coming soon.",
+ status: "coming-soon",
+ },
+ {
+ slug: "opencode",
+ title: "OpenCode",
+ description: "Coming soon.",
+ status: "coming-soon",
+ },
+];
+
+// Software packages baked into the build. `common` is on by default.
+export const SOFTWARE: SoftwareEntry[] = [
+ {
+ slug: "common",
+ title: "Common",
+ package: "@rivet-dev/agent-os-common",
+ description:
+ "coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip.",
+ },
+ {
+ slug: "build-essential",
+ title: "Build Essential",
+ package: "@rivet-dev/agent-os-build-essential",
+ description: "common + make + git + curl.",
+ },
+ {
+ slug: "git",
+ title: "git",
+ package: "@rivet-dev/agent-os-git",
+ description: "Version control.",
+ },
+ {
+ slug: "jq",
+ title: "jq",
+ package: "@rivet-dev/agent-os-jq",
+ description: "Lightweight JSON processor.",
+ },
+ {
+ slug: "ripgrep",
+ title: "ripgrep",
+ package: "@rivet-dev/agent-os-ripgrep",
+ description: "Fast recursive search (rg).",
+ },
+ {
+ slug: "fd",
+ title: "fd",
+ package: "@rivet-dev/agent-os-fd",
+ description: "Fast file finder.",
+ },
+ {
+ slug: "tree",
+ title: "tree",
+ package: "@rivet-dev/agent-os-tree",
+ description: "Display directory structure as a tree.",
+ },
+ {
+ slug: "coreutils",
+ title: "Coreutils",
+ package: "@rivet-dev/agent-os-coreutils",
+ description: "Essential POSIX commands (when not using Common).",
+ },
+];
+
+export const DEFAULT_AGENT = "pi";
+export const DEFAULT_PACKAGES = ["common"];
+
+// Sandbox mounting providers (sandbox-agent). Mounted at /sandbox.
+export const SANDBOX_PROVIDERS: SandboxProviderEntry[] = [
+ {
+ slug: "docker",
+ title: "Docker",
+ description: "Run sandboxes in local Docker containers.",
+ verified: true,
+ },
+ {
+ slug: "e2b",
+ title: "E2B",
+ description: "Secure, ephemeral cloud sandboxes.",
+ },
+ {
+ slug: "local",
+ title: "Local",
+ description: "Run sandboxes directly on the local machine.",
+ },
+ {
+ slug: "daytona",
+ title: "Daytona",
+ description: "Managed development environments.",
+ },
+ {
+ slug: "modal",
+ title: "Modal",
+ description: "Serverless cloud sandboxes.",
+ },
+ {
+ slug: "vercel",
+ title: "Vercel",
+ description: "Vercel's edge and serverless platform.",
+ },
+ {
+ slug: "computesdk",
+ title: "ComputeSDK",
+ description: "The ComputeSDK compute provider.",
+ },
+ {
+ slug: "sprites",
+ title: "Sprites",
+ description: "Sprites' cloud sandbox infrastructure.",
+ },
+];
+
+export const DEFAULT_SANDBOX_PROVIDER = "docker";
diff --git a/frontend/src/components/onboarding/agent-os/sandbox-mount-step.tsx b/frontend/src/components/onboarding/agent-os/sandbox-mount-step.tsx
new file mode 100644
index 0000000000..63acbf2045
--- /dev/null
+++ b/frontend/src/components/onboarding/agent-os/sandbox-mount-step.tsx
@@ -0,0 +1,64 @@
+import { useController } from "react-hook-form";
+import { DEFAULT_SANDBOX_PROVIDER, SANDBOX_PROVIDERS } from "./catalog";
+import { SelectCard } from "./select-card";
+
+export interface SandboxValue {
+ enabled: boolean;
+ provider?: string;
+}
+
+// Presentational sandbox-mounting selector. Off by default; when on, pick a
+// provider mounted at /sandbox.
+export function SandboxMount({
+ value,
+ onChange,
+}: {
+ value: SandboxValue;
+ onChange: (value: SandboxValue) => void;
+}) {
+ const provider = value.provider ?? DEFAULT_SANDBOX_PROVIDER;
+
+ return (
+
+
+ onChange({ ...value, enabled: !value.enabled })
+ }
+ />
+ {value.enabled ? (
+
+
+ Provider (mounted at /sandbox)
+
+
+ {SANDBOX_PROVIDERS.map((p) => (
+
+ onChange({ ...value, provider: p.slug })
+ }
+ />
+ ))}
+
+
+ {multi ? (
+
+ {selected ? (
+
+ ) : icon != null ? (
+
+ {icon}
+
+ ) : null}
+
+
+
{title}
+ {badge ? (
+
+ {badge}
+
+ ) : null}
+
+
{description}
+
+ );
+}
diff --git a/frontend/src/components/onboarding/agent-os/software-select-step.tsx b/frontend/src/components/onboarding/agent-os/software-select-step.tsx
new file mode 100644
index 0000000000..f7b1a3eca4
--- /dev/null
+++ b/frontend/src/components/onboarding/agent-os/software-select-step.tsx
@@ -0,0 +1,52 @@
+import { useController } from "react-hook-form";
+import { DEFAULT_PACKAGES, SOFTWARE } from "./catalog";
+import { SelectCard } from "./select-card";
+
+// Presentational multi-select for the software packages baked into the build.
+export function SoftwareSelect({
+ value,
+ onChange,
+}: {
+ value: string[];
+ onChange: (slugs: string[]) => void;
+}) {
+ const toggle = (slug: string) => {
+ onChange(
+ value.includes(slug)
+ ? value.filter((s) => s !== slug)
+ : [...value, slug],
+ );
+ };
+
+ return (
+
+
+ Packages are baked into the build image and are immutable after
+ deploy, so choose what your agent needs now.
+
+
+ {SOFTWARE.map((pkg) => (
+ toggle(pkg.slug)}
+ />
+ ))}
+
+
{
+ if (!value) {
+ return navigate({
+ to: ".",
+ search: (old) => ({
+ ...old,
+ modal: undefined,
+ }),
+ });
+ }
+ }}
+ />
{
+ if (!value) {
+ return navigate({
+ to: ".",
+ search: (old) => ({
+ ...old,
+ modal: undefined,
+ }),
+ });
+ }
+ }}
+ />