Orchestration

Authentication

Authenticate connections to agentOS actors using Rivet Actor connection params and hooks.

agentOS uses the same authentication system as Rivet Actors: clients send credentials as connection params, and you validate them server-side.

Clients pass credentials in params when they connect.
Validate them on the server in onBeforeConnect (throw to reject the connection), or extract user data into connection state with createConnState (read it in actions via c.conn.state).
You can declare the credential shape with agentOS<ConnParams>(...) to document what you accept, but the client’s params is unknown and is not checked against it. The real check is your hook, not the types.
The current @rivet-dev/agentos runtime is an interim stub, so wiring these hooks end to end depends on the native runtime landing.

Example

The server declares the credential shape and validates it in onBeforeConnect (throw to reject); the client passes credentials as params.

import { agentOS, setup } from "@rivet-dev/agentos";
// In a real app: import pi from "@agentos-software/pi";
import pi from "./software/pi";

// The credential shape clients pass when they connect. This documents the
// connection params; the client's params are typed as unknown, so the real
// check is the onBeforeConnect hook below.
interface ConnParams {
  authToken: string;
}

// Validate credentials server-side. onBeforeConnect receives the connection
// params and rejects the connection by throwing. Wired via the underlying Rivet
// Actor; see Actor Authentication for the full hook signatures.
export function onBeforeConnect(_c: unknown, params: ConnParams): void {
  if (typeof params?.authToken !== "string" || params.authToken.length === 0) {
    throw new Error("missing or invalid authToken");
  }
  // verify the token (JWT signature, lookup, ...) here
}

const vm = agentOS<ConnParams>({
  software: [pi],
});

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

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server";

const client = createClient<typeof registry>({ endpoint: "http://localhost:6420" });

// Pass credentials when connecting. They are forwarded as the connection
// params for your server-side validation hooks to check. `params` is typed as
// unknown, so the shape is not checked against the actor's ConnParams here.
const agent = client.vm.getOrCreate("my-agent", {
  params: { authToken: "my-jwt-token" },
});

// Actions on the handle run against the authenticated connection.
// `createSession` resolves to the session ID string.
const sessionId = await agent.createSession("claude", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agent.sendPrompt(sessionId, "List the files in the working directory.");

See Actor Authentication for JWT validation, role-based access control, external auth providers, and token caching.