The provider WebSocket is mounted at GET /ws/provider. All messages are JSON with a top-level type discriminator. Canonical Go definitions live in coordinator/protocol/messages.go; the Swift mirror lives in provider-swift/Sources/ProviderCore/Protocol/Messages.swift and shared types in provider-swift/Sources/ProviderCore/Protocol/Types.swift.
| Direction | Types |
|---|---|
| Provider → Coordinator | register, heartbeat, inference_accepted, inference_response_chunk, inference_complete, inference_error, attestation_response, code_attestation_response, load_model_status, prefetch_model_status, models_update |
| Coordinator → Provider | inference_request, cancel, attestation_challenge, runtime_status, load_model, prefetch_model, desired_models, trust_status |
Unknown provider→coordinator types are rejected by ProviderMessage.UnmarshalJSON.
Sent on WebSocket connect. Go: RegisterMessage; Swift: ProviderMessage.Register.
| Field | Type | Required | Notes |
|---|---|---|---|
type |
string | yes | "register" |
hardware |
object | yes | Hardware |
models |
array | yes | ModelInfo list |
backend |
string | yes | e.g. "mlx-swift" |
version |
string | no | Provider binary semver |
public_key |
string | no | Base64 X25519 public key for E2E encryption |
encrypted_response_chunks |
bool | no | Whether text response chunks are returned encrypted |
attestation |
raw JSON | no | Signed Secure Enclave attestation blob |
prefill_tps / decode_tps |
number | no | Benchmark throughput |
auth_token |
string | no | Device-linked provider token from darkbloom login |
private_only |
bool | no | true ⇒ only owner's self-route requests |
apns_device_token / apns_environment |
string | no | APNs code-identity attestation (v0.6.0+) |
python_hash / runtime_hash |
string | no | Runtime integrity hashes |
template_hashes |
object | no | name → SHA-256 |
privacy_capabilities |
object | no | PrivacyCapabilities |
Go: HeartbeatMessage; Swift: ProviderMessage.Heartbeat.
| Field | Type | Notes |
|---|---|---|
type |
string | "heartbeat" |
status |
string | Provider status string |
active_model |
string / null | Currently loaded model id; null means none loaded |
stats |
object | requests_served, tokens_generated |
warm_models |
array | Models currently resident in GPU memory |
system_metrics |
object | memory_pressure, cpu_usage, thermal_state |
backend_capacity |
object / null | BackendCapacity; nil for legacy providers |
| Field | Type |
|---|---|
type |
"inference_accepted" |
request_id |
string |
Go: InferenceResponseChunkMessage; Swift: ProviderMessage.InferenceResponseChunk.
| Field | Type | Notes |
|---|---|---|
type |
"inference_response_chunk" |
|
request_id |
string | |
data |
string | SSE chunk (plaintext) |
encrypted_data |
object | EncryptedPayload when E2E active |
Go: InferenceCompleteMessage; Swift: ProviderMessage.InferenceComplete.
| Field | Type | Notes |
|---|---|---|
type |
"inference_complete" |
|
request_id |
string | |
usage |
object | UsageInfo |
se_signature |
string | SE-signed response hash |
response_hash |
string | SHA-256 of response data |
Go: InferenceErrorMessage; Swift: ProviderMessage.InferenceError.
| Field | Type |
|---|---|
type |
"inference_error" |
request_id |
string |
error |
string |
status_code |
integer |
Go: AttestationResponseMessage; Swift: ProviderMessage.AttestationResponse.
| Field | Type | Notes |
|---|---|---|
type |
"attestation_response" |
|
nonce |
string | Echoed challenge nonce |
signature |
string | Base64 signature of nonce+timestamp |
status_signature |
string | Base64 signature of canonical status JSON (v0.3.11+) |
public_key |
string | Base64 X25519 public key |
hypervisor_active |
bool / null | |
rdma_disabled |
bool / null | |
sip_enabled |
bool / null | |
secure_boot_enabled |
bool / null | |
binary_hash |
string | SHA-256 of provider binary |
active_model_hash |
string | SHA-256 weight fingerprint of loaded model |
python_hash / runtime_hash |
string | Fresh runtime hashes |
template_hashes |
object | name → SHA-256 |
model_hashes |
object | model_id → SHA-256 for all active models |
Reply to the APNs-delivered code-identity challenge. Go: CodeAttestationResponseMessage; Swift: ProviderMessage.CodeAttestationResponse.
| Field | Type |
|---|---|
type |
"code_attestation_response" |
nonce |
string |
signature |
string |
Go: LoadModelStatusMessage; Swift: ProviderMessage.LoadModelStatus.
| Field | Type | Notes |
|---|---|---|
type |
"load_model_status" |
|
model_id |
string | |
status |
string | started, succeeded, failed |
error |
string | Human-readable reason on failure |
The well-known transient error "provider draining for update" is matched by the coordinator for short retry backoffs (messages.go:66-73).
Go: PrefetchModelStatusMessage; Swift: ProviderMessage.PrefetchModelStatus.
| Field | Type | Notes |
|---|---|---|
type |
"prefetch_model_status" |
|
model_id |
string | |
status |
string | started, downloading, verified, failed |
bytes_done |
integer | Best-effort progress |
bytes_total |
integer | Best-effort total |
error |
string | Failure reason |
Authoritative out-of-band update to advertised model inventory after a prefetch is verified on disk. Go: ModelsUpdateMessage; Swift: ProviderMessage.ModelsUpdate.
| Field | Type |
|---|---|
type |
"models_update" |
models |
array |
Go: InferenceRequestMessage; Swift: CoordinatorMessage.InferenceRequest.
| Field | Type | Notes |
|---|---|---|
type |
"inference_request" |
|
request_id |
string | UUID |
body |
object | Plain JSON request body (legacy / testing) |
encrypted_body |
object | EncryptedPayload — mandatory when provider has a public key |
The provider-side Swift struct uses JSONValue for body and EncryptedPayload? for encrypted_body.
Go: CancelMessage; Swift: CoordinatorMessage.Cancel.
| Field | Type |
|---|---|
type |
"cancel" |
request_id |
string |
Go: AttestationChallengeMessage; Swift: CoordinatorMessage.AttestationChallenge.
| Field | Type |
|---|---|
type |
"attestation_challenge" |
nonce |
string |
timestamp |
string |
Go: RuntimeStatusMessage; Swift: CoordinatorMessage.RuntimeStatus.
| Field | Type |
|---|---|
type |
"runtime_status" |
verified |
bool |
mismatches |
array |
Coordinator-driven eager model load. Only sent to Swift-runtime providers. Go: LoadModelMessage; Swift: CoordinatorMessage.LoadModel.
| Field | Type |
|---|---|
type |
"load_model" |
model_id |
string |
Coordinator-driven background download + verify (no GPU load). Go: PrefetchModelMessage; Swift: CoordinatorMessage.PrefetchModel.
| Field | Type | Notes |
|---|---|---|
type |
"prefetch_model" |
|
model_id |
string | |
priority |
integer | Advisory ordering hint; omitted when zero |
Declarative desired-state map sent after register and on alias changes. Only sent to Swift providers ≥ v0.5.17. Go: DesiredModelsMessage; Swift: CoordinatorMessage.DesiredModels.
| Field | Type | Notes |
|---|---|---|
type |
"desired_models" |
|
models |
array | DesiredModelEntry list |
| Field | Type | Notes |
|---|---|---|
model_name |
string | Public alias, e.g. gemma-4-26b |
desired_build |
string | Concrete build id to converge to |
previous_build |
string | Still-acceptable build during rollout |
Go: TrustStatusMessage; Swift: CoordinatorMessage.TrustStatus.
| Field | Type | Notes |
|---|---|---|
type |
"trust_status" |
|
trust_level |
string | none, self_signed, hardware |
status |
string | online, untrusted, etc. |
reason |
string | Optional reason |
Go: Hardware; Swift: HardwareInfo.
| Field | Type |
|---|---|
machine_model |
string |
chip_name |
string |
chip_family |
string |
chip_tier |
string |
memory_gb |
integer |
memory_available_gb |
number |
cpu_cores |
object |
gpu_cores |
integer |
memory_bandwidth_gbs |
number |
Go: ModelInfo; Swift: ModelInfo.
| Field | Type | Notes |
|---|---|---|
id |
string | Model id |
size_bytes |
integer | |
model_type |
string | |
quantization |
string | |
weight_hash |
string | SHA-256 fingerprint of weight files; optional |
is_vision |
bool | Only emitted when true; pre-0.6.0 providers omit |
template_render_ok |
bool / null | false excludes provider from tool requests; null omitted |
Swift's ModelInfo additionally carries estimated_memory_gb and parameters for local use; they are not sent to the coordinator.
Go: BackendCapacity; Swift: BackendCapacity.
| Field | Type |
|---|---|
slots |
array |
gpu_memory_active_gb |
number |
gpu_memory_peak_gb |
number |
gpu_memory_cache_gb |
number |
total_memory_gb |
number |
Go: BackendSlotCapacity; Swift: BackendSlotCapacity.
| Field | Type | Notes |
|---|---|---|
model |
string | |
state |
string | running, idle (loaded, no active requests), idle_shutdown, crashed, reloading |
num_running |
integer | |
num_waiting |
integer | |
max_concurrency |
integer | Optional provider-reported cap |
active_tokens |
integer | |
max_tokens_potential |
integer | |
observed_decode_tps |
number | EWMA decode TPS |
active_token_budget_used |
integer | |
active_token_budget_max |
integer | |
queued_token_budget |
integer | |
kv_bytes_per_token |
integer | Provider-side only |
"idle" means the model is loaded; treat it as warm for routing decisions.
Go: EncryptedPayload; Swift: EncryptedPayload.
| Field | Type |
|---|---|
ephemeral_public_key |
string |
ciphertext |
string |
Go: UsageInfo; Swift: UsageInfo.
| Field | Type | Notes |
|---|---|---|
prompt_tokens |
integer | |
completion_tokens |
integer | |
reasoning_tokens |
integer | Subset of completion_tokens; omitted when zero |
Go: RuntimeMismatch; Swift: RuntimeMismatch.
| Field | Type |
|---|---|
component |
string |
expected |
string |
got |
string |
Go: PrivacyCapabilities; Swift: PrivacyCapabilities.
| Field | Type |
|---|---|
text_backend_inprocess |
bool |
text_proxy_disabled |
bool |
python_runtime_locked |
bool |
dangerous_modules_blocked |
bool |
sip_enabled |
bool |
anti_debug_enabled |
bool |
core_dumps_disabled |
bool |
env_scrubbed |
bool |
hypervisor_active |
bool |