Native host access and verified return
View MarkdownBeta: this feature may change before general availability
This integration is an unqualified source candidate, disabled by default. Local tests do not establish customer access, physical erasure or successful return on hardware. An operator must qualify its fixed management image, provisioning authority, network and physical-host mapping before enabling a profile. Ordinary pool enrollment and the read-only local dashboard remain separate workflows.
The integration uses your existing access and reprovisioning authority. It does not create a new SSH service. Begin by completing the host package’s normal terminal Handback using its dedicated first connection credential. A local sticky hold or a Node deletion alone does not prove retirement.
An organization Owner or Admin uses the normal authenticated Node API. Status requires nodes:read;
starting an operation requires an organization-level nodes:write credential. Existing project-restricted
credentials cannot mutate org-scoped Nodes. Keep credentials out of JSON files and command histories.
- Read
GET /apis/nodus.dev/v1/nodes/{node}/native-access. An unavailable response means no qualified fixed mapping exists for that Node. A configured first-use response saysAwaitingFirstGrant, with generation 0 andnextGeneration: 1.approvedImageslists safe image aliases. Do not bypass a refusal with labels or direct database edits. - Send
POSTto the same path withversion: 1,action: "begin-grant", the expectedgeneration, a new immutable UUIDrequestID, an operator-approved image alias andsshPublicKeys. Supply only public keys. Host identity, images, cleanup policy and credentials are server-owned. - Read status until
customerAccessReadyis true. The normal controller queues the work; there is no manual advance command. The operator then uses the configured customer-image access path. - To return the host, send
action: "begin-return"with the same generation and a newrequestID. Omit image and keys. Access eligibility is removed before cleanup begins. - Wait for
Returned. The trusted image’s physical probe and normal enrollment must both complete. The response’sreturnedNodeidentifies the new management Node. Before another grant, retire that successor normally and use the returnednextGeneration; do not reuse an old Node or token.
Repeat an uncertain API request only with the same request UUID and identical fields. A changed duplicate
refuses. Quarantined requires operator investigation; it is not permission to reissue an external
mutation. Do not treat a timeout, an available host, or an active management image as cleanup proof.
The tested request shape is in examples/pools/native-return.json. It contains placeholder public data,
not an enabled profile or credentials. Firmware that remains writable by a customer is outside this
profile: disk erasure and GPU checks do not establish firmware integrity.