Manager host-provider protocol

ColdSnap request execution is transport-neutral. A placement manager such as Sparkrun opens an operation-scoped host session through its own cluster transport and exposes that session to the engine adapter over a local Unix socket. A future Kubernetes operator can implement the same protocol with a node API, exec subresource, or DaemonSet without changing requests, artifacts, capsules, or receipts.

The provider is activation state, not artifact identity. Its socket, bearer token, transport name, SSH options, host aliases, and credentials must never be serialized into a ColdSnap request or artifact.

Invocation

The manager starts its provider before invoking coldsnap, keeps it alive until the process exits, and supplies:

COLDSNAP_HOST_PROVIDER_SOCKET=/absolute/private/provider.sock
COLDSNAP_HOST_PROVIDER_TOKEN=<operation-scoped-random-token>

ColdSnap forwards the environment to its engine adapter. All controller-side engine executables use the shared internal/adaptercli entrypoint, which performs the capability handshake before constructing engine-specific code or allowing any host mutation. The session identity is the operation request id; the provider must authorize only the hosts named by that request’s launch units. The socket directory should be controller-private and the socket mode 0600.

This provider is required. ColdSnap has no built-in SSH, agent, or alternate transport selection; a manager may use any substrate behind this local protocol without exposing its transport details to ColdSnap.

Wire contract

Protocol format 1 uses one newline-terminated JSON request and response per Unix-socket connection. Each request contains format, a unique RPC id, the operation session, the bearer token, and operation. Responses echo format and id, and contain ok. Provider failures use ok: false and an error; a remotely executed command uses ok: true and reports its process exit_code separately.

The capability handshake is operation: capabilities. Format 1 defines:

Capability	Manager operation
exec	Execute exact argv on one authorized host, with optional binary stdin and combined output.
upload	Copy controller-local paths to one authorized host.
oci-pull / oci-push	Use controller-held registry authentication against the selected host’s image store.
huggingface-publish	Publish one host-local native payload using manager-held Hugging Face authentication.
huggingface-resolve	Resolve the published mutable revision to its immutable commit.

Binary input, output, and error_output use standard JSON base64 encoding. Arguments remain a JSON string array through the manager boundary; the transport implementation owns any final shell quoting needed by its substrate. Format 1 messages are bounded at 64 MiB because bulk checkpoint and model data move through files, registries, or object stores rather than this control channel.

Lifetime and failure behavior

Provider calls may be concurrent. Cancelling the ColdSnap process must close the provider and terminate provider-owned child sessions so long-running image or file operations are not orphaned. The provider must fail closed for an unknown capability, mismatched token/session, unrecognized host, malformed binary encoding, unknown JSON field, trailing message, oversized message, non-private socket, or response identity mismatch. Capabilities are operation-scoped: local capture and restore require exec; publication adds only the registry or Hugging Face capabilities it actually consumes.

Credentials stay with the manager. Sparkrun removes Hugging Face tokens from the ColdSnap child environment and sends them only as stdin to the short-lived helper process performing the authenticated operation. Docker credentials are likewise supplied by the controller-side Docker client; they are not installed on cluster nodes.