# Machines API URL: /runtime/api/machines # Machines API [#machines-api] Import browser-safe contracts from `@taucad/runtime/machine`. `MachineClient` exposes the admitted machines route; its `MachinePrintRequestClient` facet manages requests that require approval. Discovery, binding, preparation, transfer, and start are distinct operations. A successful preparation or upload never means a physical print has started. ## Discovery and directory [#discovery-and-directory] `MachineListProvidersInput` lists registered `MachineProvider` descriptors. `MachineDiscoverInput` starts bounded discovery for a provider and configuration; the returned `MachineDiscoveryFrame` stream carries `MachineDiscoveryEvent` values. A `MachineCandidate` contains a transient `MachineCandidateEndpoint` and untrusted `MachineClaimedIdentity`. `MachineBeginBindingInput` starts a non-secret ceremony and returns `MachineBindingOutcome`; native code completes credentials and trust. `MachineRemoveBindingInput` produces `MachineBindingRemoval` when safe. `machineCredentialReference` creates the host-local reference to a saved credential, not a portable secret. The directory's `MachineListInput`, `MachineGetInput`, and `MachineWatchInput` yield `MachineDirectorySnapshot`, `MachineDirectoryEntry`, and streamed `MachineDirectoryFrame` values. `MachineDirectoryCursor` resumes observation; it is not a mutation authority. Each entry pairs a stable descriptor with observed state and freshness. Import `prepareMachineWebSocket`, `PrepareMachineWebSocketInput`, and `PreparedMachineWebSocket` from `@taucad/runtime/transport/websocket`. The helper probes an exact authenticated HTTP(S) endpoint. A `204` yields a `RuntimeTransportFacet` whose `connect()` opens a fresh channel; `403` returns `not-granted` and `404` returns `unsupported`. Redirects and URL credentials are refused. Wait for channel readiness after connecting. `MachineDescriptor` records physical identity and capabilities. `MachineEnvelope` uses canonical metres. `MachineToolCapability`, `MachineMaterialSystem`, and `MachineQuantityDeclaration` describe tool, slot, and native-unit facts needed for compatibility checks. `MachineSnapshot` holds connection/readiness and `MachineObservedSetup`; the latter includes `MachineObservedMaterial`. Live `MachineRunSnapshot`, `MachineTemperatureSnapshot`, `MachineFanSnapshot`, `MachineMaterialUnitSnapshot`, `MachineMaterialSystemSnapshot`, `MachineNetworkSnapshot`, `MachineLightSnapshot`, and `MachineAlertSnapshot` carry observations, not commands. `MachineObservation` is the provider's pull-stream item. ## Physical operations [#physical-operations] `MachinePreparePrintInput` asks for read-only preflight of a `MachineArtifactReference` against observed setup; the `MachinePreparedPrint` result binds artifact, machine, configuration and setup digests with an expiry. `MachineUploadPrintInput` transfers exactly that preparation under a caller-retained operation id. `MachineStartPrintInput` also requires the accepted upload's transfer id and expected setup digest. `MachineControlRunInput` names `cancel`, `pause`, `resume`, or `urgent-stop` against the exact observed provider run. `MachineReconcileOperationInput` checks a prior uncertain effect. `MachineRunOperationKind` and `MachineOperationKind` distinguish run commands from upload. The resulting `MachineOperationReceipt` is `accepted`, `rejected`, or `unknown`. `MachineOperationSnapshot` is the durable projection, including planned and sending states; preserve the original operation id and reconcile an unknown outcome rather than issuing a new physical effect. `MachineCaptureStillClientInput` returns a short-lived `MachineStill` only when the provider declares `MachineStillCaptureCapability`. ## Print requests [#print-requests] `MachineRequestPrintInput` creates a `PrintRequest` for a `PrintRequester`. `PrintRequestState` distinguishes approval, transfer, start, and terminal outcomes; `PrintRequestSummary` is the list projection. `MachineListPrintRequestsInput` and `MachineWatchPrintRequestsInput` read and follow requests. `MachineResolvePrintRequestInput` supplies an approval decision; `MachineWithdrawPrintRequestInput` withdraws a pending request. These methods sit on `MachinePrintRequestClient`, not on a provider's raw session. ## Saved machine settings [#saved-machine-settings] Import persistence helpers from `@taucad/runtime/machine/settings`. A `MachineTypeId` identifies a namespaced machine type; `machineTypeIdSchema` rejects unsafe path spellings. `machineSettingsPath({ typeId })` returns `.tau/machines/settings/.json` within the project. These files contain preferences, not credentials or permission to operate hardware. `MachineSettingsRecord` stores version `1`, the machine type, an active `MachineProfileId`, and named profiles. Each `MachineSettingsProfile` maps configuration IDs to `SavedMachineConfiguration` blocks with an exact source version and sparse JSON values. Inactive and unknown blocks remain preserved. | Helper | Result and failure contract | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `readMachineSettings({ bytes, typeId })` | Returns `ReadMachineSettingsResult`: an immutable current record or `MachineSettingsFailure`. Refusals distinguish invalid data, a newer record version, and a different machine type. Preserve refused bytes. | | `serializeMachineSettings({ record })` | Validates and writes deterministic JSON with a trailing newline. Throws for invalid records or output above `machineSettingsMaximumBytes` (262,144 UTF-8 bytes). | | `readMachineConfiguration({ settings, profileId, definition, signal })` | Returns `ReadMachineConfigurationResult` with absent, current, or refused status. Current `SavedSettingsValues` are deeply immutable. | | `setMachineConfiguration({ settings, profileId, definition, values, signal })` | Produces a replacement record without I/O. Passing `undefined` removes that configuration block. Persist the returned record through a checked write. | A `SettingsSchema` admits sparse JSON objects. A `SettingsDefinition` preserves the schema's input and output values: validation cannot inject defaults or transform persisted values. `MachineProfileFailure` reports a missing selected profile. `MachineConfigurationFailure` reports an unsupported configuration version or invalid values; neither refusal falls back to defaults. `MachineSettingsProvenance`, validated by `machineSettingsProvenanceSchema`, captures project scope, type, profile, and exact configuration versions for a prepared job. Subsequent preference edits do not change captured provenance. ### Host ownership [#host-ownership] Import `MachineSettingsOwner` and its boundary types from `@taucad/runtime/host`. Construct it with an exact rooted filesystem supporting bounded streaming reads and checked writes, plus trusted definitions. Its `read` and `subscribe` methods return `MachineSettingsSnapshot`, distinguishing current, absent, refused, and unavailable records. An edit supplies a `MachineSettingsEdit`: operation ID, type ID, captured base record, and proposed next record. `MachineSettingsSave` reports saved, conflict, refused, or uncertain. Keep the operation ID and call `settlement` after an uncertain result; do not reinterpret uncertainty as success. Call `dispose` when the owner is no longer used. ## Related [#related] * [Machine provider API](/runtime/api/machine-providers) * [Host authority API](/runtime/api/host) * [Runtime architecture](/runtime/concepts/architecture)