Orchestration

Multiplayer

Connect multiple clients to one agentOS actor for collaborative coding-agent sessions with shared transcripts, state, and realtime updates.

Connect multiple clients to the same agentOS actor so all subscribers receive broadcasted session output, process logs, and shell data, enabling collaborative patterns where one user prompts and others observe.

Multiple clients observing a session

All clients connected to the same actor receive broadcasted events. This enables building collaborative UIs where multiple users watch an agent work.

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

// Client A: creates the session and sends prompts
const clientA = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});
const agentA = clientA.vm.getOrCreate("shared-agent");

const connA = agentA.connect();
connA.on("sessionEvent", (event) => {
	console.log("[A]", event);
});

await agentA.sessions.open({
	agent: "pi",
	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});
await agentA.sessions.prompt({
	content: [{ type: "text", text: "Build a REST API" }],
});

// Client B: observes the same session (in a separate process)
const clientB = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});

const connB = clientB.vm.getOrCreate("shared-agent").connect();
connB.on("sessionEvent", (event) => {
	console.log("[B]", event);
});

// Client B sees the same events as Client A

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

const vm = agentOS({
	software: [pi],
	onSessionEvent: async (_c, sessionId, event) => {
		// Server-side hook runs once per event, even with multiple clients
		console.log("Session event:", sessionId, event);
	},
});

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

registry.start();

Embedded API

Multiplayer requires Rivet Actors. An embedded VM has no connections and no broadcast: vm.onSessionEvent() and the other on* callbacks fire only in the process that created the VM. To let several clients watch one agent, either use an actor, or fan those callbacks out over your own application’s transport and let it own client identity.

Read more in the embedded API quickstart.