Skip to main content
Reference

Configuration

Configure the agentOS VM options, preview settings, and lifecycle hooks.

agentOs() accepts the following configuration object.

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: {
    // Custom filesystem mounts
    mounts: [],
    // Software packages to install in the VM (see /docs/agent-os/software)
    software: [common, pi],
    // Ports exempt from SSRF checks
    loopbackExemptPorts: [3000],
    // Host directory with node_modules
    moduleAccessCwd: "/path/to/project",
    // Extra instructions appended to agent system prompts
    additionalInstructions: "Always write tests first.",
  },

  // Preview URL token lifetimes
  preview: {
    defaultExpiresInSeconds: 3600,   // 1 hour (default)
    maxExpiresInSeconds: 86400,      // 24 hours (default)
  },

  // Called when a client connects. Throw to reject. See /docs/agent-os/authentication
  onBeforeConnect: async (c, params) => {
    const user = await verifyToken(params.token);
    if (!user) throw new Error("Unauthorized");
  },
  // Called for every session event, server-side. Runs once per event.
  onSessionEvent: async (c, sessionId, event) => {
    console.log("Session event:", sessionId, event.method);
  },
  // Called when an agent requests permission. See /docs/agent-os/permissions
  onPermissionRequest: async (c, sessionId, request) => {
    await c.respondPermission(sessionId, request.permissionId, "always");
  },
});

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

Session options

Options passed to createSession. See Sessions for full documentation.

Timeouts

SettingDefaultDescription
Action timeout15 minutesMaximum time for any single action
Sleep grace period15 minutesTime before sleeping after all activity stops

These are set internally by the agentOs() factory and cannot be overridden per-call. See Persistence & Sleep for details on the sleep lifecycle.