Enum AgentRequest 

pub enum AgentRequest {
    Ping,
    Pull {
        image: String,
        oci_platform: Option<String>,
        auth: Option<RegistryAuth>,
    },
    Query {
        image: String,
    },
    ListImages,
    GarbageCollect {
        dry_run: bool,
        purge_all: bool,
    },
    PrepareOverlay {
        image: String,
        workload_id: String,
    },
    CleanupOverlay {
        workload_id: String,
    },
    FormatStorage,
    StorageStatus,
    NetworkTest {
        url: String,
    },
    Shutdown,
    ExportLayer {
        image_digest: String,
        layer_index: usize,
    },
    VmExec {
        command: Vec<String>,
        env: Vec<(String, String)>,
        workdir: Option<String>,
        timeout_ms: Option<u64>,
        interactive: bool,
        tty: bool,
        background: bool,
    },
    Run {
        image: String,
        command: Vec<String>,
        env: Vec<(String, String)>,
        workdir: Option<String>,
        user: Option<String>,
        mounts: Vec<(String, String, bool)>,
        timeout_ms: Option<u64>,
        interactive: bool,
        tty: bool,
        detached: bool,
        persistent_overlay_id: Option<String>,
        background: bool,
    },
    Stdin {
        data: Vec<u8>,
    },
    Resize {
        cols: u16,
        rows: u16,
    },
    FileWrite {
        path: String,
        data: Vec<u8>,
        mode: Option<u32>,
    },
    FileWriteBegin {
        path: String,
        mode: Option<u32>,
        total_size: u64,
    },
    FileWriteChunk {
        data: Vec<u8>,
        done: bool,
    },
    FileRead {
        path: String,
    },
}

Agent request types (for image management and OCI operations).

Variants

Ping

Ping to check if agent is alive.

Pull

Pull an OCI image and extract layers.

Fields

image: String

Image reference (e.g., “alpine:latest”, “docker.io/library/ubuntu:22.04”).

oci_platform: Option<String>

OCI platform to pull (e.g., “linux/arm64”, “linux/amd64”).

auth: Option<RegistryAuth>

Optional registry authentication credentials.

Query

Query if an image exists locally.

Fields

image: String

Image reference.

ListImages

List all cached images.

GarbageCollect

Run garbage collection on unused layers.

Fields

dry_run: bool

If true, only report what would be deleted.

purge_all: bool

If true, delete all image manifests and configs first, making all layers unreferenced so they get collected.

PrepareOverlay

Prepare overlay rootfs for a workload.

Fields

image: String

Image reference.

workload_id: String

Unique workload ID for the overlay.

CleanupOverlay

Clean up overlay rootfs for a workload.

Fields

workload_id: String

Workload ID to clean up.

FormatStorage

Format the storage disk (first-time setup).

StorageStatus

Get storage disk status.

NetworkTest

Test network connectivity directly from the agent (not via chroot). Used to debug TSI networking.

Fields

url: String

URL to test (e.g., “http://1.1.1.1”)

Shutdown

Shutdown the agent.

ExportLayer

Export a layer as a tar archive.

Used by smolvm pack to extract OCI layers for packaging. The agent streams the layer tar data back via LayerData responses.

Fields

image_digest: String

Image digest (sha256:…).

layer_index: usize

Layer index (0-based).

VmExec

Execute a command directly in the VM (not in a container).

This runs the command in the agent’s Alpine rootfs without any container isolation. Useful for VM-level operations and debugging.

Fields

command: Vec<String>

Command and arguments.

env: Vec<(String, String)>

Environment variables.

workdir: Option<String>

Working directory in the VM.

timeout_ms: Option<u64>

Timeout in milliseconds.

interactive: bool

Interactive mode - stream I/O instead of buffering.

tty: bool

Allocate a pseudo-TTY for the command.

background: bool

Background mode - spawn and return PID immediately without waiting.

Run

Run a command in an image’s rootfs.

This prepares an overlay, chroots into it, and executes the command. Returns stdout, stderr, and exit code when the command completes.

Fields

image: String

Image reference (must be pulled first).

command: Vec<String>

Command and arguments.

env: Vec<(String, String)>

Environment variables.

workdir: Option<String>

Working directory inside the rootfs.

user: Option<String>

User inside the rootfs. If omitted, the OCI image default applies.

mounts: Vec<(String, String, bool)>

Volume mounts to bind into the container. Each tuple is (virtiofs_tag, container_path, read_only).

timeout_ms: Option<u64>

Timeout in milliseconds. If the command exceeds this duration, it will be killed and return exit code 124.

interactive: bool

Interactive mode - stream I/O instead of buffering. When true, output is streamed via Stdout/Stderr responses, and stdin can be sent via the Stdin request.

tty: bool

Allocate a pseudo-TTY for the command. Enables terminal features like colors, line editing, and signal handling.

detached: bool

Detached mode — start the container and return immediately with the container ID. Only meaningful when persistent_overlay_id is set. Returns a Completed response with stdout containing the container ID.

persistent_overlay_id: Option<String>

If set, use a persistent overlay that survives across exec sessions. The overlay is identified by this ID (typically the machine name) and reused on subsequent runs. If not set, an ephemeral overlay is created and destroyed after the run.

background: bool

Spawn the container and return immediately with the crun PID. The container runs detached; stdout/stderr go to /dev/null. Incompatible with interactive and tty.

Stdin

Send stdin data to a running interactive command.

Fields

data: Vec<u8>

Input data to send to the command’s stdin.

Resize

Resize the PTY window (for TTY mode).

Fields

cols: u16

New width in columns.

rows: u16

New height in rows.

FileWrite

Write a file inside the VM in a single message.

Use only for files up to FILE_WRITE_SINGLE_SHOT_MAX. Larger files must stream via Self::FileWriteBegin + Self::FileWriteChunk to avoid exceeding MAX_FRAME_SIZE after base64 + JSON inflation.

Fields

path: String

Absolute path in the VM filesystem.

data: Vec<u8>

File contents.

mode: Option<u32>

File mode (e.g., 0o644). None = default (0644).

FileWriteBegin

Open a streaming file upload session on this connection.

Must be followed by one or more Self::FileWriteChunk requests. The final chunk sets done: true to finalize. Dropping the connection (or sending any non-chunk request) before done aborts the session and leaves no partial file at path.

Sessions are per-connection — one session at a time.

Fields

path: String

Absolute path in the VM filesystem.

mode: Option<u32>

File mode (e.g., 0o644). None = default (0644).

total_size: u64

Expected total size in bytes. Rejected if it exceeds FILE_TRANSFER_MAX_TOTAL. The agent uses this for an early-fail check only; the actual size written is the sum of chunk byte lengths.

FileWriteChunk

Append a chunk to the currently open streaming upload. If done is true, the agent fsyncs and atomically renames the staging file onto the target path.

Fields

data: Vec<u8>

Chunk bytes. Typically FILE_WRITE_CHUNK_SIZE except for the last chunk.

done: bool

True on the final chunk; closes and renames the staging file. False on intermediate chunks.

FileRead

Read a file from the VM.

Fields

path: String

Absolute path in the VM filesystem.

Trait Implementations

impl Clone for AgentRequest

fn clone(&self) -> AgentRequest

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentRequest

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.