Where the configuration system is

QCOS is configured entirely through environment variables. There is no central config file and no Settings class — each subsystem reads the variables it needs with os.getenv(...) at import time. Practical consequences:

To change a setting, set the env var and restart the server. Values are read once at process start.
Precedence is per-variable, in code, not global.
The registry of quantum suppliers is enabled/disabled in source (ENABLED_SUPPLIERS in src/adapters/providers/registry.py), while each provider’s availability is gated by env vars (below).

Where to set variables per install channel:

Channel	Set variables in
Local / dev	your shell (`export VAR=…`) before `uvicorn`
Docker	`docker run -e VAR=… …`
Helm (`ops/deploy/helm/qcos-oem`)	chart `values.yaml` / a Secret
Appliance (ISO / cloud image)	the systemd unit / cloud-init environment
Worker (LUMI/HPC)	the worker’s environment (`src/worker/config.py`)

Accuracy note: older environment-variable lists that circulated before this page existed are out of date. QCOS does not read IONQ_API_KEY, QUANTINUUM_API_KEY, RIGETTI_API_KEY, QCOS_SECRET_KEY or PORTAL_API_URL. This page reflects what the code actually reads.

1. Profile & mode (start here)

Variable	Default	Effect
`QCOS_PROFILE`	`cloud`	`onprem` = on-premise control plane (no Azure queue required at readiness).
`QCOS_ENV`	`development`	`production` enables rate limiting + license enforcement and disables dev auth/credits.
`QCOS_BUILD_MODE`	`commercial`	`commercial` = QuantumLock licensing; `internal` = attestation. Frozen in the compiled build.
`QCOS_AUTH_REQUIRED`	`false`	`true` enforces API-key auth on every route.
`QCOS_REAL_QPU_ENABLED`	`false`	Kill-switch. `true` permits real-hardware QPU execution; else real-QPU jobs are refused.
`QCOS_ALLOW_UNPAID_QPU`	`false`	`true` bypasses the QPU payment gate (dev only).
`ENABLE_DEMO_USERS`	`false`	`true` honors the demo/admin API keys below (never in production).
`QCOS_EXPOSE_API_DOCS`	`true`	Serve the `/docs` OpenAPI UI.

2. Provider credentials — what makes a QPU “available”

Setting these flips a backend to available: true in the catalog. See Add a Quantum Computer. IBM Quantum

Variable	Default	Effect
`IBM_QUANTUM_TOKEN`	—	Primary IBM token. This is the var the registry checks to mark IBM available.
`IBM_QUANTUM_INSTANCE` / `IBM_INSTANCE`	`ibm-q/open/main`	Hub/group/project.
`IBM_QUANTUM_CHANNEL`	(passed-in)	Runtime channel override.

(Fallback aliases the IBM adapter also accepts: QCOS_IBM_TOKEN, QCOS_IBM_QUANTUM_TOKEN.) Azure Quantum (QPU routing — distinct from Azure Storage). Providers show available regardless; these are needed to actually execute:

Variable	Default	Effect
`AZURE_QUANTUM_RESOURCE_ID`	—	Full workspace resource ID (takes precedence).
`AZURE_QUANTUM_SUBSCRIPTION_ID` + `AZURE_QUANTUM_RESOURCE_GROUP` + `AZURE_QUANTUM_WORKSPACE_NAME`	—	The trio, if you don’t set the resource ID.
`AZURE_QUANTUM_LOCATION`	`westeurope`	Region.

AWS Braket

Variable	Default	Effect
`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`	—	Registry gate for Braket & AWS GPU.
`AWS_BRAKET_S3_BUCKET`	—	Required for Braket QPU providers (results bucket).
`AWS_BRAKET_REGION` / `AWS_DEFAULT_REGION`	`us-east-1`	Region.

Direct-API stub providers (each reads its own var when you implement it): IONQ_API_KEY, QUANTINUUM_USERNAME+QUANTINUUM_PASSWORD, PASQAL_API_KEY, QCS_ACCESS_KEY (Rigetti), IQM_SERVER_URL+IQM_API_TOKEN, AQT_ACCESS_TOKEN, DWAVE_API_TOKEN, OQC_API_KEY, QUANDELA_API_KEY, QUERA_API_KEY, ATOM_COMPUTING_API_KEY. (These back the src/backends/stubs/ adapters; the IQM one is a full driver at src/hal/adapters/iqm.py.)

3. GPU / HPC simulation

Variable	Default	Effect
`AZURE_STORAGE_CONNECTION_STRING`	—	Job-transport queue for LUMI & AWS GPU backends. Registry gate for `lumi` and `aws_gpu`.
`AWS_GPU_INSTANCE_TYPE`	`g5.xlarge`	EC2 GPU instance type.
`AWS_GPU_REGION`	`us-east-1`	AWS GPU region.
`QCOS_PREFER_GPU`	`lumi`	Preferred GPU provider for routing.
`QCOS_MAX_LOCAL_QUBITS`	`20`	Above this, routing prefers a GPU/HPC backend.
`SQOS_WITH_NVIDIA` (provision script)	`auto`	`1` force / `0` skip the NVIDIA Container Toolkit install.

Local GPU simulation needs no env var — the engine auto-detects CuPy / cuQuantum by import. See Add a GPU / Simulator.

4. Storage, database, secrets

Variable	Default	Effect
`QCOS_RUNTIME_STORE_URL`	—	Postgres URL for the job/result store.
`QCOS_RUNTIME_STORE_PATH`	`$TMPDIR/qcos_runtime_store.sqlite3`	SQLite path (or `memory`) when no Postgres URL.
`DATABASE_URL`	(fallback)	Main SQLAlchemy DB URL (ledger).
`QCOS_CREDENTIAL_MASTER_KEY`	—	Master key to encrypt stored BYO credentials. Required on-prem (else falls back to Key Vault / storage-string-derived key).
`AZURE_KEYVAULT_URL`	—	Key Vault for credential encryption (fallback).
`AZURE_STORAGE_CONNECTION_STRING`	—	Azure Blob/Queue/Table (also derives a credential key if the master key is unset).
`REDIS_URL`	`redis://localhost:6379/0`	Redis (streaming).

5. Scheduler (HAL device scheduling)

Variable	Default	Effect
`QCOS_SCHEDULER_ENABLED`	`true`	Per-device serialization (one job at a time per QPU).
`QCOS_SCHED_ACQUIRE_TIMEOUT_S`	`300`	Max wait for a device slot.
`QCOS_SCHED_MAX_QUEUE`	`64`	Max device queue depth before rejection.
`QCOS_HAL_DISPATCH_WORKERS`	`16`	Thread-pool size for parallel HAL dispatch.

6. Licensing (QuantumLock)

Per-device entitlement is a license feature string, not an env var: hal_max_devices:<N>, hal:*, hal:<glob>, hal_<vendor> in the active license. Operator-facing switches:

Variable	Default	Effect
`QCOS_SKIP_LICENSE_CHECK`	`false`	`true` bypasses all license checks (dev/test).
`QCOS_LICENSE_FILE`	—	Path to the license file.
`QCOS_LICENSE_KEY`	—	License key.
`QUANTUMLOCK_API_URL`	`https://quantumlock.softquantus.com/api/v1`	QuantumLock API.
`QUANTUMLOCK_VALIDATION_MODE`	`hybrid`	`online` / `offline` / `hybrid`.
`QUANTUMLOCK_GRACE_PERIOD_DAYS`	`7`	Offline grace period.

7. Auth, billing, rate limiting

Variable	Default	Effect
`QCOS_ADMIN_API_KEY`	—	Master admin API key.
`ADMIN_API_KEY` / `DEMO_API_KEY` / `PRO_DEMO_API_KEY`	—	Demo-tier keys (only when `ENABLE_DEMO_USERS=true`).
`QCOS_USE_PORTAL_AUTH`	`false`	Delegate auth to the portal (QSA).
`QCOS_PORTAL_URL` / `PORTAL_URL`	`https://platform.softquantus.com`	Portal base for auth/billing.
`QCOS_SERVICE_API_KEY` / `SERVICE_API_KEY`	—	Service-to-portal key.
`QCOS_BILLING_ENABLED`	`true`	Master billing toggle.
`QCOS_RATE_LIMIT_ENABLED`	`true` in production	Toggle rate limiting.
`QCOS_RATE_LIMIT_PER_IP` / `QCOS_RATE_LIMIT_PER_KEY`	`60` / `300`	Requests per minute.
`QCOS_CORS_ORIGINS`	—	Comma-separated CORS allowlist.

(Stripe checkout — STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_<PLAN>_PRICE_ID, payment-link vars — are only needed if you run the platform’s paid checkout; see src/entrypoints/rest/routes/enterprise/platform_routes.py.)

8. The supplier registry (enable/disable providers)

src/adapters/providers/registry.py holds SUPPLIERS and a source-level list ENABLED_SUPPLIERS. Two independent layers:

Enabled — is the supplier’s router mounted? Edit ENABLED_SUPPLIERS (source, not an env var). Currently enabled: statevector_sim, lumi, azure_quantum, ibm_quantum, braket, aws_gpu, and the native QCOS engines (qcos_neutral_atom, qcos_calibration, qcos_chemistry, qcos_algorithms, qcos_pulse, qcos_quantum_ml, qcos_advanced_physics, qcos_hybrid). Commented out: azure_gpu, google_quantum, baidu_qcompute.
Configured / available — are its requires_config env vars set? A supplier can be enabled but report NOT_CONFIGURED until credentials are present.

requires_config per supplier: ibm_quantum → IBM_QUANTUM_TOKEN; braket → AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY; aws_gpu → those + AZURE_STORAGE_CONNECTION_STRING; lumi → AZURE_STORAGE_CONNECTION_STRING; azure_quantum and the native engines → none. To add a brand-new supplier: define it in SUPPLIERS, create its router module and backend class, add its env vars to .env.example, and add its id to ENABLED_SUPPLIERS (documented in the file). For a QPU vendor, prefer a HAL driver — no core edits.

9. Worker (LUMI / HPC) — `src/worker/config.py`

The GPU/HPC worker is a separate process with its own env (.from_env()). Notable: QCOS_GPU_DEVICE_IDS (0), CUDA_VISIBLE_DEVICES (0), QCOS_MAX_QUBITS (100), QCOS_MAX_JOB_TIMEOUT (3600), QCOS_MAX_MEMORY_GB (64), QCOS_COMPUTE_BACKEND (nvidia_cudaq), QCOS_SLURM_ENABLED (false), SLURM_PARTITION (gpu), LUMI_PROJECT (project_465002463), AWS_JOB_QUEUE_URL, AWS_RESULT_QUEUE_URL.

Minimal configurations

Local dev (simulators only):

export QCOS_PROFILE=onprem QCOS_AUTH_REQUIRED=false ENABLE_DEMO_USERS=true
export QCOS_RUNTIME_STORE_PATH=memory

On-prem appliance with a real QPU enabled:

export QCOS_PROFILE=onprem QCOS_BUILD_MODE=commercial
export QCOS_REAL_QPU_ENABLED=true
export QCOS_CREDENTIAL_MASTER_KEY=***          # required on-prem
export QCOS_RUNTIME_STORE_URL=postgresql://…    # persistent job store
export QCOS_LICENSE_FILE=/etc/softqcos/license.qlicense
export IBM_QUANTUM_TOKEN=***                     # or your own driver / on-prem supplier

User Manual

Configuring the quantum OS

Where the configuration system is

1. Profile & mode (start here)

2. Provider credentials — what makes a QPU “available”

3. GPU / HPC simulation

4. Storage, database, secrets

5. Scheduler (HAL device scheduling)

6. Licensing (QuantumLock)

7. Auth, billing, rate limiting

8. The supplier registry (enable/disable providers)

9. Worker (LUMI / HPC) — `src/worker/config.py`

Minimal configurations

​Where the configuration system is

​1. Profile & mode (start here)

​2. Provider credentials — what makes a QPU “available”

​3. GPU / HPC simulation

​4. Storage, database, secrets

​5. Scheduler (HAL device scheduling)

​6. Licensing (QuantumLock)

​7. Auth, billing, rate limiting

​8. The supplier registry (enable/disable providers)

​9. Worker (LUMI / HPC) — src/worker/config.py

​Minimal configurations

Where the configuration system is

1. Profile & mode (start here)

2. Provider credentials — what makes a QPU “available”

3. GPU / HPC simulation

4. Storage, database, secrets

5. Scheduler (HAL device scheduling)

6. Licensing (QuantumLock)

7. Auth, billing, rate limiting

8. The supplier registry (enable/disable providers)

9. Worker (LUMI / HPC) — `src/worker/config.py`

Minimal configurations