Runtime

Control lifecycle, commands, files, networking, secrets, and checkpoints for one runtime.

Runtime declaration

class Runtime

Runtime access

This type is created by the SDK; do not construct it directly.

const runtime = await client.runtimes.create();
const runtime = await client.runtimes.get("runtime-id");

Runtime properties

Name	Type	Description
cachedInfo	RuntimeInfo	Most recently fetched runtime metadata.
checkpoints	RuntimeCheckpointManager	Checkpoint manager for this runtime.
displayName	string	Runtime display name.
egress	EgressManager	Egress policy manager for this runtime.
files	FileManager	File manager for this runtime.
id	string	Runtime UUID.
name	string	Runtime display name.
secrets	RuntimeSecretManager	Secret-stub manager for this runtime.

Runtime methods

boot()

Boot the runtime and optionally wait until it is ready.

Runtime.boot(options: LifecycleOptions = {}): Promise<void>

Parameters

Name	Type	Default	Description
options	LifecycleOptions	{}	Readiness polling options.

Returns

• Promise<void>

Examples

const runtime = await client.runtimes.get("worker");
await runtime.boot();
console.log(await runtime.status());

delete()

Delete the runtime.

Runtime.delete(): Promise<void>

Returns

• Promise<void>

exec()

Run a command and return its buffered output.

Runtime.exec(command: string | readonly string[], options: ExecOptions = {}): Promise<CommandResult>

Parameters

Name	Type	Default	Description
command	string | readonly string[]	Required	Shell command or argument sequence to execute.
options	ExecOptions	{}	Command environment, input, timeout, and output limits.

Returns

• Promise<CommandResult> — The command exit code and buffered output.

Throws

• ApiError If execution cannot be started or completed.

Examples

const result = await runtime.exec("python --version");
console.log(result.stdoutText);

execDetached()

Start a command without waiting for its output.

Runtime.execDetached(
  command: string | readonly string[],
  options: ExecOptions = {},
): Promise<CommandResult>

Parameters

Name	Type	Default	Description
command	string | readonly string[]	Required	Shell command or argument sequence to execute.
options	ExecOptions	{}	Options that control the operation.

Returns

• Promise<CommandResult>

heartbeat()

Alias for Runtime.status.

Runtime.heartbeat(): Promise<RuntimeStatus>

Returns

• Promise<RuntimeStatus>

pause()

Pause the runtime.

Runtime.pause(): Promise<void>

Returns

• Promise<void>

refreshInfo()

Refresh and return runtime metadata from the API.

Runtime.refreshInfo(): Promise<RuntimeInfo>

Returns

• Promise<RuntimeInfo>

resizeMemory()

Change the runtime memory limit in MiB.

Runtime.resizeMemory(newMemoryMib: number): Promise<RuntimeInfo>

Parameters

Name	Type	Default	Description
newMemoryMib	number	Required	New runtime memory limit in MiB.

Returns

• Promise<RuntimeInfo>

restore()

Create a runtime from one of this runtime’s checkpoints.

Runtime.restore(
  checkpointId: string,
  options: CreateRuntimeOptions & { name?: string | null } = {},
): Promise<Runtime>

Parameters

Name	Type	Default	Description
checkpointId	string	Required	Checkpoint UUID used by the operation.
options	CreateRuntimeOptions & { name?: string | null }	{}	Options that control the operation.

Returns

• Promise<Runtime>

resume()

Resume the runtime and optionally wait until it is ready.

Runtime.resume(options: LifecycleOptions = {}): Promise<void>

Parameters

Name	Type	Default	Description
options	LifecycleOptions	{}	Options that control the operation.

Returns

• Promise<void>

shutdown()

Shut down the runtime.

Runtime.shutdown(): Promise<void>

Returns

• Promise<void>

status()

Fetch the current runtime lifecycle status.

Runtime.status(): Promise<RuntimeStatus>

Returns

• Promise<RuntimeStatus>

updateIdleSuspendAfterSecs()

Change the idle duration before automatic suspension.

Runtime.updateIdleSuspendAfterSecs(idleSuspendAfterSecs: number | null): Promise<RuntimeInfo>

Parameters

Name	Type	Default	Description
idleSuspendAfterSecs	number | null	Required	Idle time before automatic suspension, or null to disable it.

Returns

• Promise<RuntimeInfo>

updateResources()

Update the runtime resource configuration.

Runtime.updateResources(resources: PatchRuntimeResources | Record<string, unknown>): Promise<RuntimeInfo>

Parameters

Name	Type	Default	Description
resources	PatchRuntimeResources | Record<string, unknown>	Required	Runtime resource requests and limits.

Returns

• Promise<RuntimeInfo>

waitUntilReady()

Wait until the runtime reaches the running state.

Runtime.waitUntilReady(options: WaitOptions = {}): Promise<RuntimeInfo>

Parameters

Name	Type	Default	Description
options	WaitOptions	{}	Options that control the operation.

Returns

• Promise<RuntimeInfo>