AsyncRuntime

Controls one runtime through asynchronous lifecycle and I/O operations.

Async · Sync counterpart: Runtime

AsyncRuntime declaration

class AsyncRuntime:

AsyncRuntime access

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

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

AsyncRuntime attributes

Name	Type or value	Description
`cached_info`	`RuntimeInfo`	Return the most recently fetched runtime metadata.
`egress`	`AsyncEgressManager`	Return the egress policy manager for this runtime.
`secrets`	`AsyncRuntimeSecretManager`	Return the secret-stub manager for this runtime.
`files`	`AsyncFileManager`	Return the file manager for this runtime.
`checkpoints`	`AsyncRuntimeCheckpointManager`	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()`.

AsyncRuntime methods

`refresh_info()`

Refresh and return runtime metadata from the API.

async def refresh_info() -> RuntimeInfo

Returns

RuntimeInfo

`start()`

Start the runtime and optionally wait until it is ready.

async 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.

`pause()`

Pause the runtime.

async def pause() -> None

`resume()`

Resume the runtime and optionally wait until it is ready.

async 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.

async def stop() -> None

`delete()`

Delete the runtime.

async def delete() -> None

`update_resources()`

Update the runtime resource configuration.

async 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.

async 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.

async def status() -> RuntimeStatus

Returns

RuntimeStatus

`wait_until_ready()`

Wait until the runtime reaches the running state.

async 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

`exec()`

Run a command and return its buffered output.

async 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 = await 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], 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) -> asyncio.Task[CommandResult]

Parameters

Name	Type	Default	Description
`command`	`str \| Sequence[str]`	`—`	Shell command or argument sequence to execute.
`timeout`	`float \| None`	`None`	Maximum operation time 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 command output size.

Returns

asyncio.Task[CommandResult]

`restore()`

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

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

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

AsyncRuntime