Immutable, host-selected policy for disposable offline executions.
id identifies this exact policy revision. CPU and memory are guest allocations;
disk sizes are requested guest volumes, not worker filesystem quotas. The
worker's required allocation_floor must cover its actual disk templates;
upstream reports requests even when a larger template is retained. Host admission also
reserves host_overhead_mb. No CPU-time, host RSS, process-count, or host-disk
hard quota is promised. Requests for such controls are rejected as unsupported.
Worker qualification and host isolation remain prerequisites for managed use.
Budgets cover preparation, command observation, collection, and cleanup separately. A socket timeout is never evidence of guest termination.
Summary
Functions
Convert only the supported machine allocation controls.
Create an immutable host-approved profile revision.
Revalidate profile shape and bounds; this does not attest worker enforcement.
Types
@type t() :: %SmolBox.Profile{ cleanup_ms: pos_integer(), collection_ms: pos_integer(), cpus: pos_integer(), execution_ms: pos_integer(), host_overhead_mb: pos_integer(), id: String.t(), max_file_bytes: pos_integer(), max_output_bytes: pos_integer(), max_total_file_bytes: pos_integer(), memory_mb: pos_integer(), overlay_gb: pos_integer(), preparation_ms: pos_integer(), storage_gb: pos_integer() }
Functions
@spec machine(t(), String.t(), String.t()) :: {:ok, SmolBox.MachineSpec.t()} | {:error, SmolBox.Error.t()}
Convert only the supported machine allocation controls.
@spec new(term(), term()) :: {:ok, t()} | {:error, SmolBox.Error.t()}
Create an immutable host-approved profile revision.
| Option | Default | Range/meaning |
|---|---|---|
:cpus | 1 | 1–64 guest vCPUs |
:memory_mb | 256 | 128–16,384 MiB guest allocation |
:storage_gb | 1 | 1–64 GiB storage allocation |
:overlay_gb | 1 | 1–64 GiB overlay allocation |
:host_overhead_mb | 256 | 128–16,384 MiB additional admission reservation |
:max_output_bytes | 1_048_576 | 1 byte–8 MiB of combined captured stdout/stderr |
:max_file_bytes | 1_048_576 | 1 byte–1 MiB per declared file |
:max_total_file_bytes | 4_194_304 | 1 byte–16 MiB per direction; must cover :max_file_bytes |
:preparation_ms | 60_000 | First preparation stage budget |
:execution_ms | 30_000 | Command observation budget |
:collection_ms | 30_000 | Output collection budget |
:cleanup_ms | 30_000 | Cleanup mutation budget, separate from unknown-outcome retention |
Each stage budget must be 1000–300,000 ms. A default profile is structurally valid but its 1/1 GiB disks do not meet the reference SmolVM 1.14.1 template floor. Use the actual operator-verified floor, as in the example below.
Give every changed policy a new id; managed submission matches the complete
profile against the worker's catalog. Unsupported hard quotas and networking,
mounts, ports, GPU, restart or background options return :unsupported_capability.
Example
iex> {:ok, profile} = SmolBox.Profile.new("offline-v1", storage_gb: 20, overlay_gb: 10, host_overhead_mb: 768)
iex> {profile.storage_gb, profile.overlay_gb, profile.max_output_bytes}
{20, 10, 1_048_576}@spec validate(term()) :: :ok | {:error, SmolBox.Error.t()}
Revalidate profile shape and bounds; this does not attest worker enforcement.