---
title: "POST /v1/nodes/register"
method: POST
path: "/v1/nodes/register"
tags: ["nodes"]
---

# POST /v1/nodes/register

`POST /v1/nodes/register`

## Request body

- NodeInfo
  - `address` string, required
  - `availableCpus` integer, required
  - `availableDiskGb` integer, required
  - `availableMemoryMb` integer, required
  - `id` string, required
  - `labels` object, required
  - `lastHeartbeatAt` string, nullable
  - `registeredAt` string, required
  - `runtime` string — The runtime this node speaks (e.g. `"smolvm"`). The control plane resolves a driver from this name; `smolvm_address` is that runtime's endpoint. Defaults to `"smolvm"` so a node that doesn't report a runtime (the only runtime today) is handled transparently.
  - `smolvmAddress` string, required — The runtime endpoint (HTTP address) on this node.
  - `status` string, required
  - `totalCpus` integer, required
  - `totalDiskGb` integer, required
  - `totalMemoryMb` integer, required
  - `usedCpus` number, double — Real CPU usage as fractional CPUs (e.g., 2.5 = 2.5 CPUs worth of load). Reported by the node from hypervisor/process stats. Separate from `available_cpus` (which is allocation-based bookkeeping).
  - `usedDiskGb` integer — Real disk space consumed by VM overlay/storage files in GB. Reported from filesystem stat of VM disk images. Separate from `available_disk_gb` (which reflects the entire host filesystem).
  - `usedMemoryMb` integer — Real memory usage in MB. Reported by the node from RSS of VM processes. Separate from `available_memory_mb` (which is allocation-based bookkeeping).

## Response `200`

Node registered

- NodeInfo
  - `address` string, required
  - `availableCpus` integer, required
  - `availableDiskGb` integer, required
  - `availableMemoryMb` integer, required
  - `id` string, required
  - `labels` object, required
  - `lastHeartbeatAt` string, nullable
  - `registeredAt` string, required
  - `runtime` string — The runtime this node speaks (e.g. `"smolvm"`). The control plane resolves a driver from this name; `smolvm_address` is that runtime's endpoint. Defaults to `"smolvm"` so a node that doesn't report a runtime (the only runtime today) is handled transparently.
  - `smolvmAddress` string, required — The runtime endpoint (HTTP address) on this node.
  - `status` string, required
  - `totalCpus` integer, required
  - `totalDiskGb` integer, required
  - `totalMemoryMb` integer, required
  - `usedCpus` number, double — Real CPU usage as fractional CPUs (e.g., 2.5 = 2.5 CPUs worth of load). Reported by the node from hypervisor/process stats. Separate from `available_cpus` (which is allocation-based bookkeeping).
  - `usedDiskGb` integer — Real disk space consumed by VM overlay/storage files in GB. Reported from filesystem stat of VM disk images. Separate from `available_disk_gb` (which reflects the entire host filesystem).
  - `usedMemoryMb` integer — Real memory usage in MB. Reported by the node from RSS of VM processes. Separate from `available_memory_mb` (which is allocation-based bookkeeping).

---

[API](https://skmtc.net/smolmachines/apis/smolfleet-api.md) · [All operations](https://skmtc.net/smolmachines/apis/smolfleet-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smolmachines/smolfleet-api/revisions/853ec529472a/schema)