Connect locally or over SSH

QuantEM.GPU Remote always speaks the same loopback HTTP protocol. The client location determines whether an SSH transport is needed.

Client on the CUDA host

Start the service on loopback and connect directly:

http://127.0.0.1:8780

This is useful for a local process boundary, integration tests, and service profiling. It does not make the service a different CUDA backend.

Client on another machine

Keep the service bound to loopback on the CUDA host. From the client machine, create a local SSH port forward:

ssh -N -L 8780:127.0.0.1:8780 cuda-host

The client still connects to http://127.0.0.1:8780; SSH transports that connection to the service host and provides authentication and encryption. Choose a different local port if 8780 is already occupied.

Connection ownership

The transport owns authentication, encryption, reconnect behavior, and port forwarding. The QuantEM.GPU protocol owns scientific requests, typed errors, array payloads, and provenance. Do not place credentials in dataset URLs, request bodies, logs, or cache identities.

A client should first read /api/browse/capabilities, validate the protocol name/version and implementation revision, then enable only the operations the service advertises. A network success is not scientific compatibility.

Failure behavior

Treat these conditions separately:

Condition	Client response
tunnel or service unavailable	preserve current result and offer reconnect
protocol/version mismatch	stop before issuing scientific work
source not ready	show the typed readiness reason
GPU capacity rejection	retain the requested plan; ask for an explicit policy change
stale source identity	invalidate dependent cached products

Never convert a connectivity or capacity failure into silent CPU execution, scan cropping, detector binning, or dtype reduction.