Runtime

Controls lifecycle, commands, files, networking, and secrets for one runtime.

Sync · Async counterpart: AsyncRuntime

Runtime declaration

class Runtime:

Runtime access

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

runtime = client.runtimes.create(...)
runtime = client.runtimes.get(...)

Runtime attributes

Name	Type or value	Description
cached_info	RuntimeInfo	Return the most recently fetched runtime metadata.
egress	EgressManager	Return the egress policy manager for this runtime.
secrets	RuntimeSecretManager	Return the secret-stub manager for this runtime.
files	FileManager	Return the file manager for this runtime.
checkpoints	RuntimeCheckpointManager	Return the checkpoint manager for this runtime.
id	str	Return the runtime UUID.
name	str	Return the runtime display name.
heartbeat	status	Alias for status().

Runtime methods

refresh_info()

Refresh and return runtime metadata from the API.

def refresh_info() -> RuntimeInfo

Returns

• RuntimeInfo

start()

Start the runtime and optionally wait until it is ready.

def start(*, wait: bool = True, timeout: float = 240.0, poll_interval: float = 0.5) -> None

Parameters

Name	Type	Default	Description
wait	bool	True	Wait for the operation to reach its target state.
timeout	float	240.0	Maximum operation time in seconds.
poll_interval	float	0.5	Seconds between status checks.

wait_until_ready()

Wait until the runtime reaches the running state.

def wait_until_ready(*, timeout: float = 240.0, poll_interval: float = 0.5) -> RuntimeInfo

Parameters

Name	Type	Default	Description
timeout	float	240.0	Maximum operation time in seconds.
poll_interval	float	0.5	Seconds between status checks.

Returns

• RuntimeInfo

pause()

Pause the runtime.

def pause() -> None

resume()

Resume the runtime and optionally wait until it is ready.

def resume(*, wait: bool = True, timeout: float = 240.0, poll_interval: float = 0.5) -> None

Parameters

Name	Type	Default	Description
wait	bool	True	Wait for the operation to reach its target state.
timeout	float	240.0	Maximum operation time in seconds.
poll_interval	float	0.5	Seconds between status checks.

stop()

Shut down the runtime.

def stop() -> None

delete()

Delete the runtime.

def delete() -> None

update_resources()

Update the runtime resource configuration.

def update_resources(resources: PatchRuntimeResources | Mapping[str, object]) -> RuntimeInfo

Parameters

Name	Type	Default	Description
resources	PatchRuntimeResources | Mapping[str, object]	—	Structured resource requests and limits.

Returns

• RuntimeInfo

resize_memory()

Change the runtime memory limit in MiB.

def resize_memory(new_memory_mib: int) -> RuntimeInfo

Parameters

Name	Type	Default	Description
new_memory_mib	int	—	New runtime memory limit in MiB.

Returns

• RuntimeInfo

status()

Fetch the current runtime lifecycle status.

def status() -> RuntimeStatus

Returns

• RuntimeStatus

exec()

Run a command and return its buffered output.

def exec(command: str | Sequence[str], timeout: float | None = None, env: Mapping[str, str] | None = None, stdin: bytes | str | None = None, cwd: str | None = None, max_output_bytes: int | None = None) -> CommandResult

Parameters

Name	Type	Default	Description
command	str | Sequence[str]	—	Shell command or argument sequence to execute.
timeout	float | None	None	Optional execution timeout in seconds.
env	Mapping[str, str] | None	None	Environment variables added to the command.
stdin	bytes | str | None	None	Bytes or text written to standard input.
cwd	str | None	None	Working directory used for the command.
max_output_bytes	int | None	None	Maximum buffered output size.

Returns

• CommandResult — The command exit code and buffered standard output and error.

Raises

• ApiError — If command execution cannot be started or completed.

Examples

>>> result = runtime.exec("python --version")
>>> print(result.stdout_text)
Python 3.12.0

exec_detached()

Run a command in a background worker and return a future.

def exec_detached(command: str | Sequence[str], **kwargs: Any) -> Future

Parameters

Name	Type	Default	Description
command	str | Sequence[str]	—	Shell command or argument sequence to execute.
kwargs	Any	{}	Additional keyword options forwarded to the operation.

Returns

• Future

restore()

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

def restore(checkpoint_id: str, *, name: str | None = None, **options: Any) -> Runtime

Parameters

Name	Type	Default	Description
checkpoint_id	str	—	Checkpoint UUID used by the operation.
name	str | None	None	Optional resource display name.
options	Any	{}	Additional runtime creation options.

Returns

• Runtime