There are four ways to connect a QPU to QCOS. Pick by who owns the hardware and the credentials:

#	Method	Use when	Where it’s configured
A	Built-in cloud provider	You have an account with IBM / Azure Quantum / AWS Braket	Environment variable
B	Bring-your-own (BYO) connection	A tenant/user attaches their cloud credentials at runtime	`POST /provider-connections`
C	On-premise supplier	You host the QPU yourself (or an OEM ships it)	`SupplierRegistry.SUPPLIERS`
D	Vendor HAL driver	A manufacturer ships a driver for their hardware	`pip install` a `qcos.drivers` wheel

How the catalog works: GET /api/v1/runtime/backends iterates every supplier’s providers; each provider target string becomes a backend id. A backend shows available: true only when all of its required environment variables are set. Dispatch resolves a backend_id to execution through dispatch_provider_job (built-in cloud branches first, then the HAL for plugins / on-premise / vendor drivers).

A. Built-in cloud provider — set the credential env var

The provider already exists in the registry. Set its credential(s), restart the server, and its backends flip to available: true.

Provider	Env var(s) that make it available	Example backend ids
IBM Quantum	`IBM_QUANTUM_TOKEN`	`ibm_brisbane`, `ibm_kyoto`, `ibm_osaka`, `ibm_simulator`
AWS Braket	`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (+ `AWS_BRAKET_S3_BUCKET` for real QPUs)	`sv1`, `ionq`, `rigetti`, `quera`
Azure Quantum	see note below	`ionq.aria`, `rigetti.aspen-m-3`, `quantinuum.h1-1`, `pasqal.fresnel`

export IBM_QUANTUM_TOKEN=***           # then restart the server
curl -H "Authorization: Bearer $KEY" "$QCOS/api/v1/runtime/backends?provider_source=ibm_quantum"
# ibm_brisbane now shows "available": true

Azure Quantum caveat (important, differs from older docs): the Azure providers (IonQ/Rigetti/Quantinuum/PASQAL) declare no required env var, so they always show available: true in the catalog. Their execution credentials are read at dispatch time: set AZURE_QUANTUM_RESOURCE_ID (or the trio AZURE_QUANTUM_SUBSCRIPTION_ID + AZURE_QUANTUM_RESOURCE_GROUP

AZURE_QUANTUM_WORKSPACE_NAME) plus AZURE_QUANTUM_LOCATION. The variables IONQ_API_KEY / QUANTINUUM_API_KEY / RIGETTI_API_KEY are not used for the Azure path — do not rely on them.

Config changes are read at process start — restart the server after setting any variable. Full list in Configuration.

B. Bring-your-own (BYO) credentials — per tenant/user

A tenant attaches their own cloud account at runtime, without the operator setting a server-wide env var. Only azure_quantum, ibm_quantum and braket backends support BYO (they carry supports_byo: true).

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  "$QCOS/api/v1/runtime/provider-connections" \
  -d '{"provider_type":"ibm_quantum","auth_type":"api_key","scope":"workspace",
       "name":"BYO IBM account","metadata":{"instance":"ibm-q/open/main"}}'

provider_type: ibm_quantum | azure_quantum | aws_braket | google_quantum | ionq_direct | other. scope: tenant | workspace | user. Manage with GET /provider-connections and POST /provider-connections/{id}/test. After connecting, the matching backends report supports_byo: true and jobs dispatch to the concrete provider adapter with your credentials.

C. On-premise supplier — you host the QPU

Register a SupplierType.ON_PREMISE supplier. Its provider targets become backend ids; dispatch instantiates your backend_class. On-premise devices are always classified real_qpu, so the real-QPU gates (QCOS_REAL_QPU_ENABLED, payment reservation, plan tier) apply.

from adapters.providers.registry import Provider, Supplier, SupplierRegistry, SupplierType

SupplierRegistry.SUPPLIERS["acme_quantum"] = Supplier(
    id="acme_quantum",
    name="ACME Quantum (on-premise)",
    type=SupplierType.ON_PREMISE,
    enabled=True,
    router_module="entrypoints.rest.routes.providers.statevector_sim_routes",
    backend_class="backends.your_backend.YourBackend",   # implements execute(circuit, shots) -> counts
    requires_config=[],
    providers=[
        Provider(
            id="acme_lab1", name="ACME Lab-1", num_qubits=20,
            type=SupplierType.ON_PREMISE, cost_model="flat",
            targets=["acme.lab1"],          # -> catalog backend id
            description="Customer-hosted QPU under QCOS",
            requires_config=[],
        )
    ],
)

Working example: examples/oem_console/server.py. The catalog entry provides identity + billing + gating; execution happens through a driver (usually method D). In practice you pair C (catalog) + D (driver wheel) for a real customer QPU. Behaviour (proven by tests/unit/test_onprem_byo_dispatch.py): the target appears in /backends with provider_source = your supplier id; without a qpu_reservation_id the job parks in approval_required; with payment but QCOS_REAL_QPU_ENABLED=false the door returns 403 real_qpu_disabled.

D. Vendor HAL driver — the manufacturer’s own driver

A QPU manufacturer ships a pip-installable wheel that implements the canonical QPUDriver contract and declares a qcos.drivers entry point. pip install on the QCOS host is the whole deployment — no core source, no code changes. The contract (src/hal/driver.py) — two mandatory methods:

from qcos_driver_sdk import BackendIdentity, DeviceCapabilities, HardwareSpec, QPUDriver

class AcmeDriver(QPUDriver):
    targets = ("acme.lab1",)                      # backend ids this driver serves

    def device_capabilities(self) -> DeviceCapabilities:
        return DeviceCapabilities(
            backend=BackendIdentity(id="acme.lab1", name="ACME Lab-1", provider="acme"),
            hardware=HardwareSpec(num_qubits=20, is_simulator=False),
        )

    def execute(self, circuit, shots=1024):
        # circuit arrives as OpenQASM 2.0 text at the dispatch seam
        counts = my_control_stack.run(circuit, shots)
        return {
            "job_id": "...", "backend_id": "acme.lab1", "shots": shots,
            "counts": counts, "execution_time_ms": 12.3,
            "timestamp": "...", "status": "completed",
        }

execute must return at least: job_id, backend_id, shots, counts, execution_time_ms, timestamp, status (ACOS-ISA-009). Optional overrides (with defaults): transpile_to_native, execute_batch, get_job_status, cancel_job, connect/disconnect. Ship it — one line in the wheel’s pyproject.toml:

[project.entry-points."qcos.drivers"]
acme = "acme_qcos_driver:AcmeDriver"

Or register in-process:

from hal import register_driver
register_driver("acme", AcmeDriver, targets=("acme.lab1",))

Develop & certify with the public SDK (install it on your workstation, not the server):

pip install "qcos-driver-sdk[conformance]"
qcos-driver-cert acme_qcos_driver:AcmeDriver --backend-id acme.lab1 --output report.json
# exit 0 = ACOS-ISA v1.0 certified (10/10)

Copy ReferenceSimulatorDriver (src/hal/reference.py) as a full-contract template; full worked example in examples/vendor-driver-demo/. Licensing (commercial builds): driver registration is gated by license features (hal:*, hal:<glob>, hal_<vendor>, hal_max_devices:N). Skipped when QCOS_SKIP_LICENSE_CHECK=true or in internal build mode. See docs/oem/VENDOR_ONBOARDING.md.

How dispatch resolves a backend id

dispatch_provider_job(backend_id, qasm, shots) (src/adapters/providers/router.py) — first match wins:

Built-in simulator ids → local engines (auto_sim, statevector_sim, …)
Built-in cloud ids → ionq./rigetti./quantinuum./pasqal. (Azure), ibm* (IBM), braket/sv1/tn1/dm1 (Braket)
Anything else → the HAL: registered drivers (exact) → plugin backends → on-premise suppliers → HAL wildcard drivers

If nothing matches, dispatch fails explicitly (No runtime provider adapter for backend '<id>') — a QPU id is never silently run on a simulator. Hardware drivers are serialized one-job-at-a-time per device by the scheduler; simulators run concurrently.

User Manual

Connect a quantum computer to QCOS

A. Built-in cloud provider — set the credential env var

B. Bring-your-own (BYO) credentials — per tenant/user

C. On-premise supplier — you host the QPU

D. Vendor HAL driver — the manufacturer’s own driver

How dispatch resolves a backend id

​A. Built-in cloud provider — set the credential env var

​B. Bring-your-own (BYO) credentials — per tenant/user

​C. On-premise supplier — you host the QPU

​D. Vendor HAL driver — the manufacturer’s own driver

​How dispatch resolves a backend id

A. Built-in cloud provider — set the credential env var

B. Bring-your-own (BYO) credentials — per tenant/user

C. On-premise supplier — you host the QPU

D. Vendor HAL driver — the manufacturer’s own driver

How dispatch resolves a backend id