# `SmolBox.MachineSpec`
[🔗](https://github.com/hfiguera/smolbox/blob/v0.1.3/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. Networking is offline unless an explicit
`SmolBox.NetworkPolicy` is supplied. 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 and 1.16.0 need the host's `resize2fs` for requests
below template sizes. Missing it caused file loss after stop/start in 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(),
  network: :offline | SmolBox.NetworkPolicy.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 include `:network` (offline or `SmolBox.NetworkPolicy`) and `: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 creation request and explicit network policy 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*