# `SmolBox.MachineSpec`
[🔗](https://github.com/hfiguera/smolbox/blob/v0.1.2/lib/smolbox/machine_spec.ex#L1)

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.

SmolVM 1.14.6 needs the host's `resize2fs` for requests below template sizes.
Missing it caused file loss after stop/start in the macOS validation. Verify
the host prerequisite and persistence before admitting work; see
[Compatibility](compatibility.html#macos-1-14-6-prerequisites).

# `t`

```elixir
@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()
}
```

# `new`

```elixir
@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`

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

Encode the pinned offline creation request after validation.

# `valid_name?`

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

Validate the single URL path segment used by machine operations.

# `validate`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*