--- title: "Resize a running machine." method: POST path: "/v1/machines/{id}/resize" tags: ["machines"] --- # Resize a running machine. `POST /v1/machines/{id}/resize` ## Request - Base URL: `https://api.smolmachines.com` - URL: `https://api.smolmachines.com/v1/machines/{id}/resize` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Changes a running machine's vCPUs, memory or disk in place, without a restart. Fields left out keep their current value. Memory and disk only grow; vCPUs can also shrink. The new size must fit the plan's per-machine limits and the machine's node. Requires the `machine:create` scope. ## Path parameters - `id` string, required ## Request body - ResizeMachineRequest: Change the size of a running machine. Set any of the fields; each one left out keeps its current value. RAM and disk only grow; CPUs can also shrink. - `cpus` integer, nullable: Online vCPU count. - `diskGb` integer, nullable: Storage disk size in GiB. Grow only. - `memoryMb` integer, nullable: Total guest RAM in MiB. Grow only. ## Response `200` Machine resized - MachineInfo - `arch` string, 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`. - `autoStopSeconds` integer, nullable - `branchGeneration` integer, 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. - `branchable` boolean: Whether this machine can produce live copy-on-write branches. - `cacheDisk` MachineCacheDisk: The cache disk a machine runs with. - `cacheDiskId` string, required - `intoSlot` boolean: Put in a cache slot by a restore, which needs an engine that serves slots. - `mountPath` string, required - `slot` boolean: Attached unmounted, as a slot a restore can put another cache in. - `version` integer, required - `capabilities` MachineCapabilities: Dynamic machine operations for clients that must feature-detect instead of guessing from a server or engine version. - `branch` boolean, required - `branchBatch` boolean, required - `exec` boolean, required - `fork` boolean, required - `forkBatch` boolean, required - `maxBranchBatch` integer, required - `maxForkBatch` integer, required: Legacy alias for `max_branch_batch`. - `nestedBranch` boolean, required - `nestedFork` boolean, required - `checkpointState` 'mutable' | 'freezing' | 'frozen': User-visible state of a live-RAM checkpoint. - `createdAt` string, required - `createdBy` string, nullable: The account id of whoever created the machine; null when nobody is. - `env` object, required - `ephemeral` boolean, required - `error` string, 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. - `forkGeneration` integer, nullable: Legacy alias for `branch_generation`. - `forkable` boolean: Legacy alias for `branchable`. - `id` string, required - `labels` object: Labels set at create time (or inherited from a branch source). - `lastActivityAt` string, nullable - `name` string, nullable - `network` union, required - object: No outbound access for the guest. The image PULL runs in-guest too, so a `blocked` machine whose image isn't already node-cached CANNOT fetch it and its start fails on an unreachable registry — opt into this deliberately. - `mode` 'blocked', required - object: Unrestricted outbound access. This is the DEFAULT: it matches what the `smol` CLI already sends, and means a create that omits `network` (raw API/SDK) can pull remote images out of the box instead of failing the start on an unreachable registry. Tighten with `blocked`/`allowCidrs`. - `mode` 'open', required - object - `cidrs` string[] - `hosts` string[] - `mode` 'allowCidrs', required - `parentMachineId` string, nullable: Immediate live-RAM checkpoint this machine was branched from. `null` for ordinary machines and root checkpoints. - `ports` MachinePort[]: Published ports with their allocated node host ports. - `hostPort` integer, nullable: Node host port allocated at placement (read-only; ignored on create). - `port` integer, required: Guest port the workload listens on. - `ready` boolean: 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. - `readyAt` string, 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. - `resources` MachineResources, required - `cpus` integer - `diskDurability` 'full' | 'deferred': When a machine's guest disk writes must reach the node's physical disk. - `diskGb` integer, nullable - `memoryMb` integer - `rootBranchId` string, nullable: Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage. - `rootCheckpointId` string, nullable: Legacy alias for `root_branch_id`. - `source` union, required - object - `arch` string, nullable: Requested CPU arch ("arm64"/"amd64"). Optional: an OCI image is usually multi-arch (the node pulls its own variant), so `None` means "no constraint" — but a caller that NEEDS a specific arch (e.g. x86-only binaries inside) can pin placement with it. Was previously silently dropped by deserialization. - `reference` string, required - `type` 'image', required - object - `arch` string, nullable: Canonical CPU arch the packed artifact targets ("arm64"/"amd64"). A `.smolmachine` is single-arch, so this becomes a hard placement constraint. `None` (older clients) means "no arch constraint". - `reference` string, required - `type` 'smolmachine', required - `state` string, required - `ttlSeconds` integer, nullable - `updatedAt` string, required - `url` string, 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. - `workdir` string, nullable ## Other responses - `400`: Invalid size, or memory or disk asked to shrink - `401`: Missing or invalid API key - `403`: Key lacks the required scope, or the size exceeds the plan - `404`: Not found - `409`: Machine is not running, or its node has no room for the new size - `429`: Rate limited; retry after the Retry-After header - `500`: Internal error ## Changes - **2026-10-16** `bc31fc04a568`: 1 info - endpoint added [Operation history](https://skmtc.dev/smolmachines/apis/smolfleet-api/changes/v1/machines/:id/resize/post.md) --- [API](https://skmtc.dev/smolmachines/apis/smolfleet-api.md) - [All operations](https://skmtc.dev/smolmachines/apis/smolfleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smolmachines/apis/smolfleet-api/revisions/bc31fc04a568?raw)