Interface ISandboxClient

Namespace

OpenShell

Assembly

OpenShell.Sdk.dll

Sandbox lifecycle operations, scoped to one workspace.

public interface ISandboxClient

Methods

CreateAsync(string?, SandboxSpec, CreateSandboxOptions?, CancellationToken)

Creates a sandbox. The call returns before the sandbox is ready; see WaitReadyAsync(string, WaitOptions?, CancellationToken).

ValueTask<Sandbox> CreateAsync(string? name, SandboxSpec spec, CreateSandboxOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

spec SandboxSpec

options CreateSandboxOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

CreateFromTemplateAsync(string?, string, SandboxSpec?, CreateSandboxOptions?, CancellationToken)

Creates a sandbox from a reusable workload template; spec may override fields.

ValueTask<Sandbox> CreateFromTemplateAsync(string? name, string templateName, SandboxSpec? spec = null, CreateSandboxOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

templateName string

spec SandboxSpec

options CreateSandboxOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

DeleteAsync(string, DeleteOptions?, CancellationToken)

Deletes a sandbox. Inspect Outcome; Accepted means cleanup is pending.

ValueTask<DeletionResult> DeleteAsync(string name, DeleteOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options DeleteOptions

cancellationToken CancellationToken

Returns

ValueTask<DeletionResult>

GetAsync(string, CancellationToken)

Gets a sandbox by name.

ValueTask<Sandbox> GetAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

List(ListOptions?)

Lists sandboxes lazily, page by page.

Pager<Sandbox> List(ListOptions? options = null)

Parameters

options ListOptions

Returns

Pager<Sandbox>

ListIdsAsync(ListOptions?, CancellationToken)

Lists the ids of all matching sandboxes, across every page.

ValueTask<IReadOnlyList<string>> ListIdsAsync(ListOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options ListOptions

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<string>>

ResumeAsync(string, ResumeSandboxOptions?, CancellationToken)

Resumes a suspended sandbox from its retained memory state. The sandbox returns as Starting and becomes ready with a new runtime generation (see WaitReadyAsync(string, WaitOptions?, CancellationToken)). Fails with Conflict (FAILED_PRECONDITION) unless the sandbox is suspended.

ValueTask<Sandbox> ResumeAsync(string name, ResumeSandboxOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options ResumeSandboxOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

ResumePendingUpdateAsync(string, ulong, UpdateSandboxOptions?, CancellationToken)

Completes a sandbox update that failed or was interrupted, by sending an update with the current resource version and no fields. Fails with Conflict when no update is pending.

ValueTask<Sandbox> ResumePendingUpdateAsync(string name, ulong expectedResourceVersion, UpdateSandboxOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

expectedResourceVersion ulong

options UpdateSandboxOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

StartAsync(string, CancellationToken)

Starts a stopped sandbox. Starting a suspended sandbox discards its retained memory state; see ResumeAsync(string, ResumeSandboxOptions?, CancellationToken).

ValueTask<Sandbox> StartAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

StopAsync(string, CancellationToken)

Stops a running sandbox.

ValueTask<Sandbox> StopAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

SuspendAsync(string, CancellationToken)

Suspends a ready sandbox: it is frozen with its memory retained, moving through Suspending to Suspended (see WaitSuspendedAsync(string, WaitOptions?, CancellationToken)). Repeating the call while suspending or suspended is safe. Fails with Conflict (FAILED_PRECONDITION) in any other phase, or when the compute driver does not support suspension.

ValueTask<Sandbox> SuspendAsync(string name, CancellationToken cancellationToken = default)

Parameters

name string

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

UpdateAsync(string, ulong, SandboxUpdate, UpdateSandboxOptions?, CancellationToken)

Changes the configuration of a stopped sandbox through the SandboxUpdates service, which the gateway serves only when [openshell.gateway] enable_sandbox_updates = true. The update does not start the sandbox.

ValueTask<Sandbox> UpdateAsync(string name, ulong expectedResourceVersion, SandboxUpdate update, UpdateSandboxOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

expectedResourceVersion ulong

update SandboxUpdate

options UpdateSandboxOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

Remarks

expectedResourceVersion is required (compare-and-swap): a stale version fails with Conflict (ABORTED). The sandbox must be stopped, otherwise the call fails with Conflict (FAILED_PRECONDITION), as it does while the feature is disabled. Workload changes (image, command, environment) a compute driver cannot apply fail with Unimplemented; label and annotation changes work on every driver.

A failed or interrupted update leaves a pending intent that blocks start and stop until ResumePendingUpdateAsync(string, ulong, UpdateSandboxOptions?, CancellationToken) completes it.

WaitDeletedAsync(string, WaitOptions?, CancellationToken)

Polls until the sandbox name is gone, or resolves to a different id when ExpectedSandboxId is set.

ValueTask WaitDeletedAsync(string name, WaitOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options WaitOptions

cancellationToken CancellationToken

Returns

ValueTask

WaitReadyAsync(string, WaitOptions?, CancellationToken)

Polls until the sandbox is ready (or completed). Fails fast when the sandbox is suspending or suspended.

ValueTask<Sandbox> WaitReadyAsync(string name, WaitOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options WaitOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

WaitStoppedAsync(string, WaitOptions?, CancellationToken)

Polls until the sandbox is stopped. Fails fast when the sandbox is suspending or suspended.

ValueTask<Sandbox> WaitStoppedAsync(string name, WaitOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options WaitOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>

WaitSuspendedAsync(string, WaitOptions?, CancellationToken)

Polls until the sandbox is suspended. Fails when it reaches a phase other than Suspending or Suspended.

ValueTask<Sandbox> WaitSuspendedAsync(string name, WaitOptions? options = null, CancellationToken cancellationToken = default)

Parameters

name string

options WaitOptions

cancellationToken CancellationToken

Returns

ValueTask<Sandbox>