Struct A3sBoxClient 

pub struct A3sBoxClient { /* private fields */ }

Runtime-backed SDK client for local a3s-box state.

Implementations

impl A3sBoxClient

pub fn new() -> Self

Create a client for the default a3s-box home.

pub fn from_home(home: impl Into<PathBuf>) -> Self

Create a client rooted at a custom a3s-box home directory.

pub fn with_paths(paths: A3sBoxPaths) -> Self

Create a client using explicit state paths.

pub fn with_execution_manager( paths: A3sBoxPaths, execution_manager: Arc<dyn ExecutionManager>, ) -> Self

Create a client with an explicit backend-neutral execution manager.

This keeps lifecycle calls on the same canonical facade used by the CLI and remote compatibility service while allowing an embedding application to inject its own manager implementation.

pub fn with_execution_services( paths: A3sBoxPaths, execution_manager: Arc<dyn ExecutionManager>, execution_session_manager: Arc<dyn ExecutionSessionManager>, ) -> Self

Create a client with explicit typed lifecycle and session managers.

This is useful for embedding the E2B-style crate::Sandbox facade in another local process without selecting backends by string.

pub fn with_image_cache_size(self, image_cache_size: u64) -> Self

Override the image cache size used when opening the runtime image store.

pub fn paths(&self) -> &A3sBoxPaths

Return the state paths used by this client.

pub fn runtime_diagnostics(&self) -> RuntimeDiagnostics

Collect local runtime diagnostics without spawning the CLI.

pub fn runtime_disk_usage(&self) -> Result<RuntimeDiskUsage>

Collect local runtime disk usage without spawning the CLI.

impl A3sBoxClient

pub fn list_boxes(&self, options: ListBoxesOptions) -> Result<Vec<BoxSummary>>

List box records from the shared state file.

pub fn get_box(&self, query: &str) -> Result<Option<BoxSummary>>

Get one box by exact id, short id, id prefix, or name.

pub fn remove_box( &self, query: &str, request: RemoveBox, ) -> Result<RemoveBoxSummary>

Remove a box record and its host-side runtime resources.

By default active boxes are rejected. Pass RemoveBox::force to mirror CLI-style forced removal, which only signals a recorded PID after the PID identity check still matches the original box process.

pub fn prune_boxes(&self) -> Result<Vec<RemoveBoxSummary>>

Remove all created, stopped, and dead boxes from SDK-managed state.

Running and paused boxes are kept. Host-side runtime resources for each removed box are cleaned up after the records are removed under the state lock, so concurrent readers no longer observe pruned boxes.

pub fn pause_box(&self, query: &str) -> Result<BoxSummary>

Pause a running box by stopping its host shim process and updating state.

This mirrors the CLI’s pause semantics for the direct SDK surface: only a currently running box can be paused, and stale or reused PIDs are rejected before any signal is sent.

pub fn unpause_box(&self, query: &str) -> Result<BoxSummary>

Resume a paused box by continuing its host shim process and updating state.

pub async fn stop_box( &self, query: &str, request: StopBox, ) -> Result<StopBoxSummary>

Stop a running or paused box with guest-first graceful shutdown.

pub fn read_box_logs( &self, query: &str, options: ReadBoxLogsOptions, ) -> Result<Vec<BoxLogLine>>

Read recent logs for one box from the runtime log files.

The SDK follows the same source preference as the CLI: structured logs/container.json first, then the raw console log as a fallback. This method is a bounded snapshot reader; it does not follow live output.

pub fn list_box_stats(&self) -> Result<Vec<BoxStatsSummary>>

Collect host-side resource usage snapshots for all active boxes.

CPU and memory are read from the recorded shim process. Network counters are read from the runtime netproxy stats file when it exists. This is a bounded snapshot reader; it does not stream and does not exec into the guest.

pub fn get_box_stats(&self, query: &str) -> Result<Option<BoxStatsSummary>>

Collect one host-side resource usage snapshot by exact id, short id, id prefix, or name. Returns None when the box is not active or its host process is no longer available.

pub async fn list_images(&self) -> Result<Vec<ImageSummary>>

List cached images from the runtime image store.

pub async fn get_image( &self, reference_or_digest: &str, ) -> Result<Option<ImageSummary>>

Resolve one image by reference or digest.

pub async fn inspect_image( &self, reference_or_digest: &str, ) -> Result<Option<ImageInspectSummary>>

Inspect one cached image’s local OCI configuration.

pub async fn image_history( &self, reference_or_digest: &str, ) -> Result<Option<Vec<ImageHistoryEntry>>>

Read one cached image’s OCI build history.

pub async fn tag_image(&self, request: TagImage) -> Result<ImageSummary>

Add a new tag pointing at an existing cached image.

pub async fn remove_image(&self, reference_or_digest: &str) -> Result<()>

Remove one cached image by reference or digest.

pub async fn evict_images(&self) -> Result<Vec<String>>

Evict least-recently-used images until the image cache is under its limit.

pub async fn pull_image(&self, request: PullImage) -> Result<ImageSummary>

Pull an OCI image through the runtime image puller and cache it locally.

pub async fn build_image( &self, request: BuildImage, ) -> Result<BuildImageSummary>

Build an OCI image with the runtime Dockerfile build engine.

pub async fn push_image(&self, request: PushImage) -> Result<PushImageSummary>

Push a locally cached image through the runtime registry pusher.

pub fn list_volumes(&self) -> Result<Vec<VolumeSummary>>

List named volumes from the runtime volume store.

pub fn get_volume(&self, name: &str) -> Result<Option<VolumeSummary>>

Get one named volume.

pub fn create_volume(&self, request: CreateVolume) -> Result<VolumeSummary>

Create a named volume.

pub fn remove_volume(&self, name: &str, force: bool) -> Result<VolumeSummary>

Remove a named volume.

pub fn prune_volumes(&self) -> Result<Vec<String>>

Remove all unused named volumes.

pub fn list_networks(&self) -> Result<Vec<NetworkSummary>>

List networks from the runtime network store.

pub fn get_network(&self, name: &str) -> Result<Option<NetworkSummary>>

Get one network.

pub fn create_network(&self, request: CreateNetwork) -> Result<NetworkSummary>

Create a bridge network.

pub fn remove_network(&self, name: &str) -> Result<NetworkSummary>

Remove a network. The runtime rejects networks that still have endpoints.

pub fn prune_networks(&self) -> Result<Vec<String>>

Remove all unused non-predefined networks.

A network is unused when it has no endpoints and no box record references it by network_name or bridge network_mode. Docker-style predefined networks (bridge, host, none) are never pruned.

pub fn connect_network( &self, network: &str, box_query: &str, ) -> Result<NetworkEndpointSummary>

Attach an inactive box record to a network and allocate an endpoint.

Hot-plug for active boxes is not supported by the runtime yet, so this mirrors the CLI rule: stop the box before changing its network.

pub fn disconnect_network( &self, network: &str, box_query: &str, ) -> Result<NetworkEndpointSummary>

Detach an inactive box record from a network.

pub fn list_snapshots(&self) -> Result<Vec<SnapshotSummary>>

List VM snapshots from the runtime snapshot store.

pub fn get_snapshot(&self, id: &str) -> Result<Option<SnapshotSummary>>

Get one VM snapshot by id.

pub fn remove_snapshot(&self, id: &str) -> Result<bool>

Remove one VM snapshot by id.

pub fn create_snapshot( &self, box_query: &str, request: CreateSnapshot, ) -> Result<SnapshotSummary>

Create a VM snapshot from a stopped box’s on-disk root filesystem.

pub fn restore_snapshot( &self, snapshot_query: &str, request: RestoreSnapshot, ) -> Result<BoxSummary>

Restore a snapshot into a new, created box record.

pub fn prune_snapshots( &self, max_count: usize, max_bytes: u64, ) -> Result<Vec<String>>

Prune old snapshots according to count and byte limits.

A value of 0 means unlimited for each limit, matching the runtime store.

pub async fn exec_box( &self, query: &str, request: &ExecRequest, ) -> Result<ExecOutput>

Execute a command in a running box through the runtime exec client.

pub async fn execute_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, request: ExecRequest, ) -> Result<ExecOutput>

Execute a command through the generation-fenced managed session facade.

pub async fn transfer_box_file( &self, query: &str, request: &FileRequest, ) -> Result<FileResponse>

Transfer a file to or from a running box through the runtime exec client.

pub async fn transfer_execution_file( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, request: FileRequest, ) -> Result<FileResponse>

Transfer a file through the generation-fenced managed session facade.

pub async fn filesystem_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, request: FilesystemRequest, ) -> Result<FilesystemResponse>

Access filesystem metadata through the generation-fenced session facade.

pub async fn heartbeat_box(&self, query: &str) -> Result<bool>

Check whether a running box’s exec server responds to heartbeat.

pub async fn signal_box_main(&self, query: &str, signal: i32) -> Result<bool>

Ask the guest to deliver a signal to the main process.

pub async fn spawn_box_main( &self, query: &str, spec_json: Option<&[u8]>, ) -> Result<bool>

Ask a deferred-main guest to spawn its configured main process.

pub async fn exec_client(&self, query: &str) -> Result<ExecClient>

Open the runtime exec client for a running box.

pub async fn pty_client(&self, query: &str) -> Result<PtyClient>

Open the runtime PTY client for a running box.

pub async fn attestation_report( &self, query: &str, request: &AttestationRequest, ) -> Result<AttestationReport>

Request a raw attestation report through the runtime attestation client.

pub fn open_image_store(&self) -> Result<ImageStore>

Open the runtime image store rooted at this client’s state paths.

pub fn volume_store(&self) -> VolumeStore

Open the runtime volume store rooted at this client’s state paths.

pub fn network_store(&self) -> NetworkStore

Open the runtime network store rooted at this client’s state paths.

pub fn snapshot_store(&self) -> Result<SnapshotStore>

Open the runtime snapshot store rooted at this client’s state paths.

impl A3sBoxClient

pub fn image(&self, context_dir: impl Into<PathBuf>) -> ImageBuilder

Start a fluent local OCI image build.

pub fn volume(&self, name: impl Into<String>) -> VolumeBuilder

Start a fluent named-volume creation request.

pub fn network(&self, name: impl Into<String>) -> NetworkBuilder

Start a fluent bridge-network creation request.

impl A3sBoxClient

pub async fn create_box( &self, request: CreateExecutionRequest, operation_id: &OperationId, ) -> Result<ExecutionReservation>

Persist an unstarted execution through the canonical lifecycle facade.

pub async fn start_box( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, ) -> Result<ExecutionLease>

Start a previously created execution with generation fencing.

pub async fn run_box( &self, request: CreateExecutionRequest, operation_id: &OperationId, ) -> Result<ExecutionLease>

Atomically create or recover and then start an execution.

pub async fn inspect_execution( &self, execution_id: &ExecutionId, ) -> Result<ExecutionStatus>

Inspect the generation-fenced state of a managed execution.

pub async fn create_execution_snapshot( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, snapshot_id: &ExecutionSnapshotId, ) -> Result<ExecutionSnapshot>

Atomically capture one running or paused execution filesystem.

The runtime temporarily quiesces a running execution, publishes the snapshot under the validated identifier, and restores the prior stable state before returning.

pub async fn execution_snapshot_size( &self, snapshot_id: &ExecutionSnapshotId, ) -> Result<Option<u64>>

Return the published size of a runtime-managed filesystem snapshot.

pub async fn delete_execution_snapshot( &self, snapshot_id: &ExecutionSnapshotId, ) -> Result<bool>

Delete a runtime-managed filesystem snapshot.

The runtime refuses deletion while a live execution still uses the snapshot as its immutable copy-on-write lower.

pub async fn read_execution_logs( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, ) -> Result<Vec<LogEntry>>

Read structured stdout/stderr entries for one generation.

pub async fn pause_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, keep_memory: bool, ) -> Result<ExecutionLease>

Pause a managed execution through its resolved backend.

pub async fn resume_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, ) -> Result<ExecutionLease>

Resume a managed execution through its resolved backend.

pub async fn restart_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, operation_id: &OperationId, options: RestartExecutionOptions, ) -> Result<ExecutionLease>

Restart a managed execution under an idempotent operation identity.

pub async fn kill_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, ) -> Result<KillOutcome>

Kill a managed execution and release runtime-owned resources.

pub async fn remove_execution( &self, execution_id: &ExecutionId, generation: ExecutionGeneration, ) -> Result<bool>

Remove one terminal execution through the canonical lifecycle facade.

pub async fn reconcile_operation( &self, operation_id: &OperationId, ) -> Result<ReconcileOutcome>

Reconcile one idempotent create operation after caller or service restart.

impl A3sBoxClient

pub fn sandbox(&self, image: impl Into<String>) -> SandboxBuilder

Start a fluent builder for a local Sandbox.

Trait Implementations

impl Clone for A3sBoxClient

fn clone(&self) -> A3sBoxClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for A3sBoxClient

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for A3sBoxClient

fn default() -> Self

Returns the “default value” for a type.