SmolBox.MachineSpec (SmolBox v0.1.0)

Create a disposable machine from a host-approved prepared artifact.

The path is on the worker host, not the Elixir host. The operator must verify its immutable digest and architecture before approving it. SmolBox never enables networking to fetch a missing image. Starts use /bin/true and never restart the workload automatically. No host mounts, sockets, GPU, or ports are exposed by this contract.

Disk sizes are requests. SmolVM 1.14.1 copies larger disk templates without shrinking them, while its API still reports the request. Low-level callers must verify runtime/artifact disk geometry; managed workers require an explicit allocation floor. A matching create reply alone is not enforcement.

Summary

Types

t()

Functions

new(name, artifact_path, options \\ [])

Describe a machine using a name and absolute .smolmachine path on the worker.

to_wire(spec)

Encode the pinned offline creation request after validation.

valid_name?(name)

Validate the single URL path segment used by machine operations.

validate(spec)

Revalidate the machine name, worker artifact path and allocation bounds.

Types

t()

@type t() :: %SmolBox.MachineSpec{
  artifact_path: String.t(),
  cpus: pos_integer(),
  memory_mb: pos_integer(),
  name: String.t(),
  overlay_gb: pos_integer(),
  storage_gb: pos_integer()
}

Functions

new(name, artifact_path, options \\ [])

@spec new(term(), term(), term()) :: {:ok, t()} | {:error, SmolBox.Error.t()}

Describe a machine using a name and absolute .smolmachine path on the worker.

Names have at most 31 lowercase letters, digits, underscores or hyphens and start with a letter/digit; SmolBox.Identity.machine_name/1 generates opaque names. Options are :cpus (default 1, range 1–64), :memory_mb (256, 128–16,384), :storage_gb and :overlay_gb (each 1, range 1–64). For the reference templates, explicitly request 20/10 GiB disks. Construction does not read the artifact.

Pass the validated value to SmolBox.Client.create/2. Use SmolBox.Profile and SmolBox.ExecutionSpec for managed submissions instead.

to_wire(spec)

@spec to_wire(t()) :: {:ok, map()} | {:error, SmolBox.Error.t()}

Encode the pinned offline creation request after validation.

valid_name?(name)

@spec valid_name?(term()) :: boolean()

Validate the single URL path segment used by machine operations.

validate(spec)

@spec validate(term()) :: :ok | {:error, SmolBox.Error.t()}

Revalidate the machine name, worker artifact path and allocation bounds.