General

Core API

Full API reference for @rivet-dev/agent-os-core — VM lifecycle, filesystem, processes, networking, shells, and agent sessions.

Lifecycle

Method	Signature	Description
`create`	`static create(options?: AgentOsOptions): Promise<AgentOs>`	Create and boot a new VM
`dispose`	`dispose(): Promise<void>`	Shut down the VM and all sessions

Method	Signature	Description
`readFile`	`readFile(path: string): Promise<Uint8Array>`	Read a file
`writeFile`	`writeFile(path: string, content: string \| Uint8Array): Promise<void>`	Write a file
`readFiles`	`readFiles(paths: string[]): Promise<BatchReadResult[]>`	Batch read multiple files
`writeFiles`	`writeFiles(entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>`	Batch write multiple files (creates parent dirs)
`mkdir`	`mkdir(path: string): Promise<void>`	Create a directory
`readdir`	`readdir(path: string): Promise<string[]>`	List directory entries
`readdirRecursive`	`readdirRecursive(path: string, options?: ReaddirRecursiveOptions): Promise<DirEntry[]>`	Recursively list directory contents with metadata
`stat`	`stat(path: string): Promise<VirtualStat>`	Get file/directory metadata
`exists`	`exists(path: string): Promise<boolean>`	Check if a path exists
`move`	`move(from: string, to: string): Promise<void>`	Rename/move a file or directory
`delete`	`delete(path: string, options?: { recursive?: boolean }): Promise<void>`	Delete a file or directory
`mountFs`	`mountFs(path: string, config: MountConfig): void`	Mount a filesystem at the given path
`unmountFs`	`unmountFs(path: string): void`	Unmount a filesystem

Method	Signature	Description
`exec`	`exec(command: string, options?: ExecOptions): Promise<ExecResult>`	Execute a shell command and wait for completion
`spawn`	`spawn(command: string, args: string[], options?: SpawnOptions): ManagedProcess`	Spawn a long-running process
`listProcesses`	`listProcesses(): SpawnedProcessInfo[]`	List processes started via `spawn()`
`allProcesses`	`allProcesses(): ProcessInfo[]`	List all kernel processes across all runtimes
`processTree`	`processTree(): ProcessTreeNode[]`	Get processes organized as a parent-child tree
`getProcess`	`getProcess(pid: number): SpawnedProcessInfo`	Get info about a specific spawned process
`stopProcess`	`stopProcess(pid: number): void`	Send SIGTERM to a process
`killProcess`	`killProcess(pid: number): void`	Send SIGKILL to a process

Method	Signature	Description
`fetch`	`fetch(port: number, request: Request): Promise<Response>`	Send an HTTP request to a service running inside the VM

Method	Signature	Description
`openShell`	`openShell(options?: OpenShellOptions): ShellHandle`	Open an interactive shell with PTY support

Method	Signature	Description
`createSession`	`createSession(agentType: AgentType, options?: CreateSessionOptions): Promise<Session>`	Launch an agent and return a session
`listSessions`	`listSessions(): SessionInfo[]`	List active sessions
`getSession`	`getSession(sessionId: string): Session`	Get a session by ID
`resumeSession`	`resumeSession(sessionId: string): Session`	Retrieve an active session by ID
`destroySession`	`destroySession(sessionId: string): Promise<void>`	Gracefully cancel and close a session

Method	Signature	Description
`listAgents`	`listAgents(): AgentRegistryEntry[]`	List registered agents with installation status

Method	Signature	Description
`prompt`	`prompt(text: string): Promise<JsonRpcResponse>`	Send a prompt and wait for the response
`cancel`	`cancel(): Promise<JsonRpcResponse>`	Cancel ongoing agent work
`close`	`close(): void`	Kill the agent process and clean up
`onSessionEvent`	`onSessionEvent(handler: SessionEventHandler): void`	Subscribe to session update notifications
`onPermissionRequest`	`onPermissionRequest(handler: PermissionRequestHandler): void`	Subscribe to permission requests
`respondPermission`	`respondPermission(permissionId: string, reply: PermissionReply): Promise<JsonRpcResponse>`	Reply to a permission request
`setMode`	`setMode(modeId: string): Promise<JsonRpcResponse>`	Set the session mode (e.g., “plan”)
`getModes`	`getModes(): SessionModeState \| null`	Get available modes
`setModel`	`setModel(model: string): Promise<JsonRpcResponse>`	Set the model
`setThoughtLevel`	`setThoughtLevel(level: string): Promise<JsonRpcResponse>`	Set reasoning level
`getConfigOptions`	`getConfigOptions(): SessionConfigOption[]`	Get available config options
`getEvents`	`getEvents(options?: GetEventsOptions): JsonRpcNotification[]`	Get event history
`getSequencedEvents`	`getSequencedEvents(options?: GetEventsOptions): SequencedEvent[]`	Get event history with sequence numbers
`rawSend`	`rawSend(method: string, params?: Record<string, unknown>): Promise<JsonRpcResponse>`	Send an arbitrary ACP request

Session properties: sessionId, agentType, capabilities, agentInfo, closed

AgentOsOptions — VM creation options (commandDirs, loopbackExemptPorts, moduleAccessCwd, mounts, additionalInstructions)
CreateSessionOptions — Session options (cwd, env, mcpServers, skipOsInstructions, additionalInstructions)

ProcessInfo — Kernel process info (pid, ppid, pgid, sid, driver, command, args, cwd, status, exitCode, startTime, exitTime)
SpawnedProcessInfo — Info for processes created via spawn() (pid, command, args, running, exitCode)
ProcessTreeNode — ProcessInfo with children: ProcessTreeNode[]

AgentType — "pi" | "opencode"
AgentConfig — Agent configuration (acpAdapter, agentPackage, prepareInstructions)
AgentRegistryEntry — Registry entry (id, acpAdapter, agentPackage, installed)