Authentication

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.

server.tsclient.ts

server.ts

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

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();

client.ts

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; the server hook validates them.
const agent = client.vm.getOrCreate("my-agent", {
  params: { authToken: "my-jwt-token" },
});

const session = await agent.createSession("claude", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agent.sendPrompt(session.sessionId, "List the files in the working directory.");

See Full Example

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