Interface VmActions

The vm.* action surface as the SERVER defines it. Each handler receives the RivetKit action context (c) as its first argument; RivetKit strips that context when projecting these onto the client handle, so callers invoke e.g. handle.createSession("claude", { env: { ANTHROPIC_API_KEY } }).

The string index signature satisfies RivetKit's Actions constraint.

interface VmActions {
    cancelCronJob(c: any, id: string): Promise<void>;
    cancelPrompt(c: any, sessionId: string): Promise<JsonRpcResponse>;
    cancelSession(c: any, sessionId: string): Promise<JsonRpcResponse>;
    closeProcessStdin(c: any, pid: number): Promise<void>;
    closeSession(c: any, sessionId: string): Promise<void>;
    closeShell(c: any, shellId: string): Promise<void>;
    connectTerminal(c: any, options?: ConnectTerminalOptions): Promise<number>;
    createSession(
        c: any,
        agentType: string,
        options?: CreateSessionOptions,
    ): Promise<SessionRecord>;
    createSignedPreviewUrl(
        c: any,
        port: number,
        expiresInSeconds?: number,
    ): Promise<PreviewUrl>;
    delete(
        c: any,
        path: string,
        options?: { recursive?: boolean },
    ): Promise<void>;
    destroySession(c: any, sessionId: string): Promise<void>;
    exec(c: any, command: string, options?: ExecOptions): Promise<ExecResult>;
    execArgv(
        c: any,
        command: string,
        args?: readonly string[],
        options?: ExecOptions,
    ): Promise<ExecResult>;
    exists(c: any, path: string): Promise<boolean>;
    getConfigOptions(c: any, sessionId: string): Promise<SessionConfigOption[]>;
    getModes(c: any, sessionId: string): Promise<SessionModeState | null>;
    getProcess(c: any, pid: number): Promise<SpawnedProcessInfo>;
    getSequencedEvents(
        c: any,
        sessionId: string,
        options?: GetSequencedEventsOptions,
    ): Promise<SequencedSessionEvent[]>;
    getSessionEvents(
        c: any,
        sessionId: string,
    ): Promise<PersistedSessionEvent[]>;
    killProcess(c: any, pid: number): Promise<void>;
    listCronJobs(c: any): Promise<CronJobInfo[]>;
    listPersistedSessions(c: any): Promise<PersistedSessionRecord[]>;
    listProcesses(c: any): Promise<SpawnedProcessInfo[]>;
    listSessions(c: any): Promise<SessionRecord[]>;
    mkdir(
        c: any,
        path: string,
        options?: { recursive?: boolean },
    ): Promise<void>;
    move(c: any, from: string, to: string): Promise<void>;
    openShell(c: any, options?: OpenShellOptions): Promise<{ shellId: string }>;
    prompt(c: any, sessionId: string, text: string): Promise<PromptResult>;
    readdir(c: any, path: string): Promise<string[]>;
    readdirRecursive(
        c: any,
        path: string,
        options?: ReaddirRecursiveOptions,
    ): Promise<DirEntry[]>;
    readFile(c: any, path: string): Promise<Uint8Array<ArrayBufferLike>>;
    readFiles(c: any, paths: string[]): Promise<BatchReadResult[]>;
    resizeShell(
        c: any,
        shellId: string,
        cols: number,
        rows: number,
    ): Promise<void>;
    respondPermission(
        c: any,
        sessionId: string,
        permissionId: string,
        reply: PermissionReply,
    ): Promise<JsonRpcResponse>;
    scheduleCron(
        c: any,
        options: SerializableCronJobOptions,
    ): Promise<ScheduledCronJob>;
    sendPrompt(
        c: any,
        sessionId: string,
        prompt: string,
    ): Promise<PromptResult>;
    setMode(
        c: any,
        sessionId: string,
        modeId: string,
    ): Promise<JsonRpcResponse>;
    setModel(
        c: any,
        sessionId: string,
        model: string,
    ): Promise<JsonRpcResponse>;
    setThoughtLevel(
        c: any,
        sessionId: string,
        level: string,
    ): Promise<JsonRpcResponse>;
    snapshotRootFilesystem(c: any): Promise<RootSnapshotExport>;
    spawn(
        c: any,
        command: string,
        args?: string[],
        options?: SpawnOptions,
    ): Promise<{ pid: number }>;
    spawnProcess(c: any, command: string, args?: string[]): Promise<number>;
    stat(c: any, path: string): Promise<VirtualStat>;
    stopProcess(c: any, pid: number): Promise<void>;
    vmFetch(
        c: any,
        port: number,
        path: string,
        options?: VmFetchOptions,
    ): Promise<VmFetchResponse>;
    waitProcess(c: any, pid: number): Promise<number>;
    writeFile(
        c: any,
        path: string,
        content: string | Uint8Array<ArrayBufferLike>,
    ): Promise<void>;
    writeFiles(c: any, entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>;
    writeProcessStdin(
        c: any,
        pid: number,
        data: string | Uint8Array<ArrayBufferLike>,
    ): Promise<void>;
    writeShell(
        c: any,
        shellId: string,
        data: string | Uint8Array<ArrayBufferLike>,
    ): Promise<void>;
    [action: string]: (c: any, ...args: any[]) => any;
}

Indexable

[action: string]: (c: any, ...args: any[]) => any
Index signature required by RivetKit's Actions constraint.

Methods

cancelCronJob

cancelCronJob(c: any, id: string): Promise<void>
Cancel a registered cron job by id.
Parameters
- c: any
- id: string
Returns Promise<void>
- Defined in mod.ts:774

cancelPrompt

cancelPrompt(c: any, sessionId: string): Promise<JsonRpcResponse>
Cancel the in-flight prompt for a session (leaves the session open).
Parameters
- c: any
- sessionId: string
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:611

cancelSession

cancelSession(c: any, sessionId: string): Promise<JsonRpcResponse>
Cancel ongoing agent work for a session.
Parameters
- c: any
- sessionId: string
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:613

closeProcessStdin

closeProcessStdin(c: any, pid: number): Promise<void>
Close a spawned process's stdin stream.
Parameters
- c: any
- pid: number
Returns Promise<void>
- Defined in mod.ts:687

closeSession

closeSession(c: any, sessionId: string): Promise<void>
Tear down an ACP session abruptly.
Parameters
- c: any
- sessionId: string
Returns Promise<void>
- Defined in mod.ts:617

closeShell

closeShell(c: any, shellId: string): Promise<void>
Close a shell and free its PTY.
Parameters
- c: any
- shellId: string
Returns Promise<void>
- Defined in mod.ts:710

connectTerminal

connectTerminal(c: any, options?: ConnectTerminalOptions): Promise<number>
Connect a terminal (PTY) to the VM and return its pid.
Parameters
- c: any
- Optionaloptions: ConnectTerminalOptions
Returns Promise<number>
- Defined in mod.ts:699

createSession

createSession(
    c: any,
    agentType: string,
    options?: CreateSessionOptions,
): Promise<SessionRecord>
Create an ACP session against a registered agent and return its record.
Parameters
- c: any
- agentType: string
- Optionaloptions: CreateSessionOptions
Returns Promise<SessionRecord>
- Defined in mod.ts:601

createSignedPreviewUrl

createSignedPreviewUrl(
    c: any,
    port: number,
    expiresInSeconds?: number,
): Promise<PreviewUrl>
Create a time-limited, token-based preview URL for a VM port.
Parameters
- c: any
- port: number
- OptionalexpiresInSeconds: number
Returns Promise<PreviewUrl>
- Defined in mod.ts:759

delete

delete(c: any, path: string, options?: { recursive?: boolean }): Promise<void>
Delete a path (optionally recursive).
Parameters
- c: any
- path: string
- Optionaloptions: { recursive?: boolean }
Returns Promise<void>
- Defined in mod.ts:742

destroySession

destroySession(c: any, sessionId: string): Promise<void>
Gracefully destroy a session (cancel pending work, then close).
Parameters
- c: any
- sessionId: string
Returns Promise<void>
- Defined in mod.ts:619

exec

exec(c: any, command: string, options?: ExecOptions): Promise<ExecResult>
Run a command line to completion and capture its output.
Parameters
- c: any
- command: string
- Optionaloptions: ExecOptions
Returns Promise<ExecResult>
- Defined in mod.ts:659

execArgv

execArgv(
    c: any,
    command: string,
    args?: readonly string[],
    options?: ExecOptions,
): Promise<ExecResult>
Run a command (argv form, no shell) to completion and capture output.
Parameters
- c: any
- command: string
- Optionalargs: readonly string[]
- Optionaloptions: ExecOptions
Returns Promise<ExecResult>
- Defined in mod.ts:661

exists

exists(c: any, path: string): Promise<boolean>
Check whether a path exists.
Parameters
- c: any
- path: string
Returns Promise<boolean>
- Defined in mod.ts:738

getConfigOptions

getConfigOptions(c: any, sessionId: string): Promise<SessionConfigOption[]>
Get the configurable options (model, thought level, ...) for a session.
Parameters
- c: any
- sessionId: string
Returns Promise<SessionConfigOption[]>
- Defined in mod.ts:640

getModes

getModes(c: any, sessionId: string): Promise<SessionModeState | null>
Get the available + current modes for a session.
Parameters
- c: any
- sessionId: string
Returns Promise<SessionModeState | null>
- Defined in mod.ts:638

getProcess

getProcess(c: any, pid: number): Promise<SpawnedProcessInfo>
Get info about a single spawned process.
Parameters
- c: any
- pid: number
Returns Promise<SpawnedProcessInfo>
- Defined in mod.ts:679

getSequencedEvents

getSequencedEvents(
    c: any,
    sessionId: string,
    options?: GetSequencedEventsOptions,
): Promise<SequencedSessionEvent[]>
Replay in-memory session events (live reconnection); newer than since.
Parameters
- c: any
- sessionId: string
- Optionaloptions: GetSequencedEventsOptions
Returns Promise<SequencedSessionEvent[]>
- Defined in mod.ts:644

getSessionEvents

getSessionEvents(c: any, sessionId: string): Promise<PersistedSessionEvent[]>
Replay persisted session events from durable storage (transcript history).
Parameters
- c: any
- sessionId: string
Returns Promise<PersistedSessionEvent[]>
- Defined in mod.ts:650

killProcess

killProcess(c: any, pid: number): Promise<void>
Force-kill a running process by pid (SIGKILL).
Parameters
- c: any
- pid: number
Returns Promise<void>
- Defined in mod.ts:693

listCronJobs

listCronJobs(c: any): Promise<CronJobInfo[]>
List the cron jobs registered on this VM.
Parameters
- c: any
Returns Promise<CronJobInfo[]>
- Defined in mod.ts:772

listPersistedSessions

listPersistedSessions(c: any): Promise<PersistedSessionRecord[]>
List persisted session records (including for VMs not currently running).
Parameters
- c: any
Returns Promise<PersistedSessionRecord[]>
- Defined in mod.ts:655

listProcesses

listProcesses(c: any): Promise<SpawnedProcessInfo[]>
List processes spawned via spawn.
Parameters
- c: any
Returns Promise<SpawnedProcessInfo[]>
- Defined in mod.ts:677

listSessions

listSessions(c: any): Promise<SessionRecord[]>
List the sessions currently tracked by this VM.
Parameters
- c: any
Returns Promise<SessionRecord[]>
- Defined in mod.ts:615

mkdir

mkdir(c: any, path: string, options?: { recursive?: boolean }): Promise<void>
Create a directory (optionally recursive).
Parameters
- c: any
- path: string
- Optionaloptions: { recursive?: boolean }
Returns Promise<void>
- Defined in mod.ts:722

move

move(c: any, from: string, to: string): Promise<void>
Move/rename a path.
Parameters
- c: any
- from: string
- to: string
Returns Promise<void>
- Defined in mod.ts:740

openShell

openShell(c: any, options?: OpenShellOptions): Promise<{ shellId: string }>
Open an interactive shell (PTY) and return its id.
Parameters
- c: any
- Optionaloptions: OpenShellOptions
Returns Promise<{ shellId: string }>
- Defined in mod.ts:697

prompt

prompt(c: any, sessionId: string, text: string): Promise<PromptResult>
Alias of sendPrompt: send a prompt and accumulate the agent's reply.
Parameters
- c: any
- sessionId: string
- text: string
Returns Promise<PromptResult>
- Defined in mod.ts:609

readdir

readdir(c: any, path: string): Promise<string[]>
List the immediate entries of a directory.
Parameters
- c: any
- path: string
Returns Promise<string[]>
- Defined in mod.ts:728

readdirRecursive

readdirRecursive(
    c: any,
    path: string,
    options?: ReaddirRecursiveOptions,
): Promise<DirEntry[]>
Recursively list directory entries with metadata.
Parameters
- c: any
- path: string
- Optionaloptions: ReaddirRecursiveOptions
Returns Promise<DirEntry[]>
- Defined in mod.ts:730

readFile

readFile(c: any, path: string): Promise<Uint8Array<ArrayBufferLike>>
Read a file from the VM filesystem.
Parameters
- c: any
- path: string
Returns Promise<Uint8Array<ArrayBufferLike>>
- Defined in mod.ts:714

readFiles

readFiles(c: any, paths: string[]): Promise<BatchReadResult[]>
Read several files in one call, reporting per-file content/errors.
Parameters
- c: any
- paths: string[]
Returns Promise<BatchReadResult[]>
- Defined in mod.ts:720

resizeShell

resizeShell(c: any, shellId: string, cols: number, rows: number): Promise<void>
Resize a shell's PTY.
Parameters
- c: any
- shellId: string
- cols: number
- rows: number
Returns Promise<void>
- Defined in mod.ts:703

respondPermission

respondPermission(
    c: any,
    sessionId: string,
    permissionId: string,
    reply: PermissionReply,
): Promise<JsonRpcResponse>
Reply to a pending permission request raised by the agent.
Parameters
- c: any
- sessionId: string
- permissionId: string
- reply: PermissionReply
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:621

scheduleCron

scheduleCron(
c: any,
options: SerializableCronJobOptions,
): Promise<ScheduledCronJob>
Schedule a serializable cron job inside the VM.
Parameters
- c: any
- options: SerializableCronJobOptions
Returns Promise<ScheduledCronJob>
- Defined in mod.ts:767

sendPrompt

sendPrompt(c: any, sessionId: string, prompt: string): Promise<PromptResult>
Send a prompt to an existing session and accumulate the agent's reply.
Parameters
- c: any
- sessionId: string
- prompt: string
Returns Promise<PromptResult>
- Defined in mod.ts:607

setMode

setMode(c: any, sessionId: string, modeId: string): Promise<JsonRpcResponse>
Switch the active mode (e.g. "plan", "auto") for a session.
Parameters
- c: any
- sessionId: string
- modeId: string
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:628

setModel

setModel(c: any, sessionId: string, model: string): Promise<JsonRpcResponse>
Switch the active model for a session.
Parameters
- c: any
- sessionId: string
- model: string
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:630

setThoughtLevel

setThoughtLevel(
    c: any,
    sessionId: string,
    level: string,
): Promise<JsonRpcResponse>
Switch the thought/reasoning level for a session.
Parameters
- c: any
- sessionId: string
- level: string
Returns Promise<JsonRpcResponse>
- Defined in mod.ts:632

snapshotRootFilesystem

snapshotRootFilesystem(c: any): Promise<RootSnapshotExport>
Export a serializable snapshot of the VM root filesystem.
Parameters
- c: any
Returns Promise<RootSnapshotExport>
- Defined in mod.ts:748

spawn

spawn(
    c: any,
    command: string,
    args?: string[],
    options?: SpawnOptions,
): Promise<{ pid: number }>
Spawn a long-running process and return its pid.
Parameters
- c: any
- command: string
- Optionalargs: string[]
- Optionaloptions: SpawnOptions
Returns Promise<{ pid: number }>
- Defined in mod.ts:668

spawnProcess

spawnProcess(c: any, command: string, args?: string[]): Promise<number>
Spawn a process inside the VM and return its pid.
Parameters
- c: any
- command: string
- Optionalargs: string[]
Returns Promise<number>
- Defined in mod.ts:675

stat

stat(c: any, path: string): Promise<VirtualStat>
Stat a path.
Parameters
- c: any
- path: string
Returns Promise<VirtualStat>
- Defined in mod.ts:736

stopProcess

stopProcess(c: any, pid: number): Promise<void>
Gracefully stop a process (SIGTERM).
Parameters
- c: any
- pid: number
Returns Promise<void>
- Defined in mod.ts:691

vmFetch

vmFetch(
    c: any,
    port: number,
    path: string,
    options?: VmFetchOptions,
): Promise<VmFetchResponse>
Proxy an HTTP request to a port inside the VM and return the response.
Parameters
- c: any
- port: number
- path: string
- Optionaloptions: VmFetchOptions
Returns Promise<VmFetchResponse>
- Defined in mod.ts:752

waitProcess

waitProcess(c: any, pid: number): Promise<number>
Wait for a process to exit and return its exit code.
Parameters
- c: any
- pid: number
Returns Promise<number>
- Defined in mod.ts:689

writeFile

writeFile(
    c: any,
    path: string,
    content: string | Uint8Array<ArrayBufferLike>,
): Promise<void>
Write a file into the VM filesystem.
Parameters
- c: any
- path: string
- content: string | Uint8Array<ArrayBufferLike>
Returns Promise<void>
- Defined in mod.ts:716

writeFiles

writeFiles(c: any, entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>
Write several files in one call, reporting per-file success.
Parameters
- c: any
- entries: BatchWriteEntry[]
Returns Promise<BatchWriteResult[]>
- Defined in mod.ts:718

writeProcessStdin

writeProcessStdin(
    c: any,
    pid: number,
    data: string | Uint8Array<ArrayBufferLike>,
): Promise<void>
Write data to a spawned process's stdin.
Parameters
- c: any
- pid: number
- data: string | Uint8Array<ArrayBufferLike>
Returns Promise<void>
- Defined in mod.ts:681

writeShell

writeShell(
    c: any,
    shellId: string,
    data: string | Uint8Array<ArrayBufferLike>,
): Promise<void>
Write input to a shell's PTY.
Parameters
- c: any
- shellId: string
- data: string | Uint8Array<ArrayBufferLike>
Returns Promise<void>
- Defined in mod.ts:701

Interface VmActions

Indexable

Index

Methods

Methods

cancelCronJob

Parameters

Returns Promise<void>

cancelPrompt

Parameters

Returns Promise<JsonRpcResponse>

cancelSession

Parameters

Returns Promise<JsonRpcResponse>

closeProcessStdin

Parameters

Returns Promise<void>

closeSession

Parameters

Returns Promise<void>

closeShell

Parameters

Returns Promise<void>

connectTerminal

Parameters

Returns Promise<number>

createSession

Parameters

Returns Promise<SessionRecord>

createSignedPreviewUrl

Parameters

Returns Promise<PreviewUrl>

delete

Parameters

Returns Promise<void>

destroySession

Parameters

Returns Promise<void>

exec

Parameters

Returns Promise<ExecResult>

execArgv

Parameters

Returns Promise<ExecResult>

exists

Parameters

Returns Promise<boolean>

getConfigOptions

Parameters

Returns Promise<SessionConfigOption[]>

getModes

Parameters

Returns Promise<SessionModeState | null>

getProcess

Parameters

Returns Promise<SpawnedProcessInfo>

getSequencedEvents

Parameters

Returns Promise<SequencedSessionEvent[]>

getSessionEvents

Parameters

Returns Promise<PersistedSessionEvent[]>

killProcess

Parameters

Returns Promise<void>

listCronJobs

Parameters

Returns Promise<CronJobInfo[]>

listPersistedSessions

Parameters

Returns Promise<PersistedSessionRecord[]>

listProcesses

Parameters

Returns Promise<SpawnedProcessInfo[]>

listSessions

Parameters

Returns Promise<SessionRecord[]>

mkdir

Parameters

Returns Promise<void>