Lifecycle

Wait for, keep alive, give a lifetime to, suspend, resume, restart, resize, detach and delete a sandbox.

Lifecycle calls on a Sandbox handle. They act on the container or VM.

Python programs usually use the high-level API instead: Sandbox lifecycle.

Lifecycle methods#

Methods of Sandbox.

Sandbox.wait_ready#

Waits until every probe passes.

async def wait_ready(self, probes: List[ReadinessProbe], timeout_ms: int) -> None

Async · Raises CuaError

Sandbox.refresh#

Fresh info (status from the provider).

async def refresh(self) -> SandboxInfo

Returns SandboxInfo · Async · Raises CuaError

Sandbox.keep_alive#

Extends the sandbox's lease by seconds, for a provider that has one.

async def keep_alive(self, seconds: int) -> None

Async · Raises CuaError

Sandbox.set_lifetime#

Gives this local sandbox a lifetime of seconds from now, replacing any earlier one: the cua daemon then deletes it (on_expire "delete", the default) or suspends it ("suspend"), whether or not this process is still running. Needs the cua daemon (an embedded runtime records the lifetime; the next daemon enforces it).

async def set_lifetime(self, seconds: int, on_expire: Optional[str]) -> None

Async · Raises CuaError

Sandbox.expires_at_unix#

When this sandbox's lifetime ends (Sandbox.set_lifetime), as Unix seconds; None when it has none.

async def expires_at_unix(self) -> Optional[int]

Returns Option<i64> · Async · Raises CuaError

Sandbox.suspend#

Suspends.

async def suspend(self) -> None

Async · Raises CuaError

Sandbox.resume#

Resumes.

async def resume(self) -> None

Async · Raises CuaError

Sandbox.restart#

Restarts.

async def restart(self) -> None

Async · Raises CuaError

Sandbox.resize#

Gives a local VM another shape: cpus vCPUs, memory_mb MiB of memory and a disk grown to disk_gb GiB (each None keeps it). The VM stops and boots again from its own disk, so its memory and running processes do not survive; its files do. Returns once it is ready again. A disk never shrinks. Containers, Fleet and other providers' sandboxes are refused (Unsupported).

async def resize(self, cpus: Optional[int], memory_mb: Optional[int], disk_gb: Optional[int]) -> None

Async · Raises CuaError (Unsupported)

Sandbox.delete#

Deletes (local: removes it; direct: forgets it; your cloud: deletes the machine).

async def delete(self) -> None

Async · Raises CuaError

parse_sandbox_ref#

Parses a sandbox ref: local:<name>, cloud:<name>, direct:<host:port>, relay:<machine-id>, a legacy spelling (space://cloud/<name>, url:<addr>, a URL), or a bare name.

def parse_sandbox_ref(input: str) -> SandboxRefParts

Returns SandboxRefParts · Raises CuaError

Example

import cua
 
print([cua.parse_sandbox_ref(r).id for r in ("space://cloud/box", "url:10.0.0.5:3211", "box")])
# ['cloud:box', 'direct:10.0.0.5:3211', 'box']

qualify_sandbox_ref#

Qualifies name for a lookup: local = true narrows a bare name to local:<name>, false to cloud:<name>, None keeps it (a bare name is then searched across locations). A qualified ref elsewhere than local asks is an InvalidArgument.

def qualify_sandbox_ref(name: str, local: Optional[bool] = None) -> str

Returns String · Raises CuaError (InvalidArgument)

Example

import cua
 
print([cua.qualify_sandbox_ref("box", True), cua.qualify_sandbox_ref("box", False), cua.qualify_sandbox_ref("box", None)])
# ['local:box', 'cloud:box', 'box']

ambiguous_sandbox_candidates#

The qualified candidates an AmbiguousSandbox message lists (empty for any other message).

def ambiguous_sandbox_candidates(message: str) -> List[str]

Returns Vec<String>

SandboxRefParts record#

A parsed sandbox ref.

Returned by parse_sandbox_ref.