# Native host access and verified return

> Operator workflow for a separately qualified full-host access integration.

Source: https://www.nodus-compute.ai/docs/guides/pools/native-host-return/
Build revision: 364dd57152437ff26b6a4ebad4f685ff5f4fcb5f

**Beta:** this feature may change.

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.

1. 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 says `AwaitingFirstGrant`, with generation 0 and `nextGeneration: 1`. `approvedImages` lists safe image aliases. Do not bypass a refusal with labels or direct database edits.
2. Send `POST` to the same path with `version: 1`, `action: "begin-grant"`, the expected `generation`, a new immutable UUID `requestID`, an operator-approved image alias and `sshPublicKeys`. Supply only public keys. Host identity, images, cleanup policy and credentials are server-owned.
3. Read status until `customerAccessReady` is true. The normal controller queues the work; there is no manual advance command. The operator then uses the configured customer-image access path.
4. To return the host, send `action: "begin-return"` with the same generation and a new `requestID`. Omit image and keys. Access eligibility is removed before cleanup begins.
5. Wait for `Returned`. The trusted image’s physical probe and normal enrollment must both complete. The response’s `returnedNode` identifies the new management Node. Before another grant, retire that successor normally and use the returned `nextGeneration`; 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.
