machines

Create a machine.

Changed on Oct 16, 2026

Creates (and by default boots) a machine from an OCI image or packed artifact. Requires the machine:create scope.

post/v1/machines

Request

Base URL
https://api.smolmachines.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/smolmachines/apis/smolfleet-api/docs/v1/machines/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

autoStopSecondsinteger nullable

branchableboolean

Create this machine as a branch source: it boots with cloneable live RAM so POST /v1/machines/:id/branches can create independent copy-on-write children. Default false.

commandstring[]

Optional workload command (argv) that overrides the source image's or .smolmachine artifact's own entrypoint+cmd when the machine starts, so a deploy of an off-the-shelf image can say what to run/serve. Empty (default) = use the source's own entrypoint, preserving prior behavior.

credentialsstring[]

Names of stored credentials this machine binds. Each gives the guest a placeholder in the credential's variable; the node substitutes the value only on HTTPS requests to the credential's hosts, so the machine never holds it.

envobject

ephemeralboolean

labelsobject

Free-form key/value labels for finding the machine again later (GET /v1/machines?label=key=value). At most 32; keys are 1-63 chars of [a-z0-9]([a-z0-9._/-]*[a-z0-9])?, values up to 255 chars.

namestring nullable

nestedVirtboolean

Expose nested virtualization (VMX/SVM) to the guest so it can run its own hypervisor. Refused with 422 nested_virt_unavailable unless this platform enables it, so a request for it is never silently dropped. Default false.

publicboolean

Opt in to UNAUTHENTICATED public ingress: when true (and the machine has a published port), its *.apps//proxy URL is reachable by anyone. Default false — a published port is reachable only via the authenticated path.

ttlSecondsinteger nullable

workdirstring nullable

Example request

{
  "cacheDisk": {
    "cache": "deps"
  }
}

Response

Machine created

archstring nullable

The machine's actual CPU arch (arm64/amd64): the arch of the node it runs on, falling back to source.arch (a .smolmachine's pinned arch) when the machine is unplaced or its node is gone. None only when neither is known. Lets the console show an arch badge for every machine, including ones whose source pinned no arch. Populated by the server's machine_info.

autoStopSecondsinteger nullable

branchGenerationinteger nullable

Zero for a root branch source, one for its children, and so on.

branchState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

branchableboolean

Whether this machine can produce live copy-on-write branches.

checkpointState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

createdAtstring required

createdBystring nullable

The account id of whoever created the machine; null when nobody is.

envobject required

ephemeralboolean required

errorstring nullable

When [Self::state] is "error", a human-readable reason the machine failed — the latest control-plane error event (e.g. "start failed: …", "auto-start failed: …", or "machine stuck in creating state"). null for machines that are not in an error state. Gives clients something actionable instead of a bare error with no explanation.

forkGenerationinteger nullable

Legacy alias for branch_generation.

forkableboolean

Legacy alias for branchable.

idstring required

labelsobject

Labels set at create time (or inherited from a branch source).

lastActivityAtstring nullable

namestring nullable

parentMachineIdstring nullable

Immediate live-RAM checkpoint this machine was branched from. null for ordinary machines and root checkpoints.

readyboolean

Whether the machine is READY to do work. state == "started" only means the VM process launched on the node — the guest OS and your in-VM workload still need a moment to boot. ready becomes true once the guest agent is reachable (an exec/connect will succeed) and, if the machine publishes a port, that port is accepting connections. Wait for ready (poll GET /v1/machines/:id) before expecting an in-guest worker to have started or before connecting to it — do NOT act on started alone.

readyAtstring nullable

When a probe first observed this machine serving (RFC3339), or null.

This is a readiness gate, not a boot timestamp: it is stamped when the published port accepts a connection (or, for a machine with no published ports, when its guest agent answers), and it is cleared on every stop so a restart must re-prove itself. A short-lived machine may finish its whole life as null here without anything being wrong. Use createdAt if you want when the machine came into existence.

rootBranchIdstring nullable

Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage.

rootCheckpointIdstring nullable

Legacy alias for root_branch_id.

statestring required

ttlSecondsinteger nullable

updatedAtstring required

urlstring nullable

Public ingress URL for the machine's first published port, when the machine is started and the control plane has a public base URL configured. null for stopped machines, machines with no published port, or when the deployment exposes no public base URL.