Run the QCOS quantum OS locally on CPU, GPU or your own QPU

This guide details how to install, configure, and execute QCOS locally on your Macbook, workstation, or local server. QCOS runs your simulations in two places, and you choose per workload:

On your own machine. The daemon, SDK, CLI and MCP server run on your desktop or local server, using your own CPU or GPU. Circuits never leave your hardware, which is what you want for iterating quickly and for work you cannot send to a third party.
On CPU in the SoftQuantus Cloud. When a circuit outgrows your machine, the same code runs against cloud CPU simulation instead, without rewriting anything.

Physical QPUs and HPC clusters in the SoftQuantus Cloud are billed with compute credits. Running QCOS requires an active licence, which the next step covers.

Step 1: Acquire and Activate Your License

To run local simulations, you need a cryptographic license key:

Log in to the Softquantus Research Platform.
Subscribe to the QCOS Annual License (€1,500/year) and retrieve your license key (e.g., QLOCK-XXXX-XXXX-XXXX-XXXX).
Run the following commands in your local terminal to install the client packages and activate the license:

# 1. Install QCOS CLI and Python SDK via pip
pip install softqcos-cli softqcos-sdk

# 2. Activate the license locally (binds the signature to your hardware and fetches the local license file)
softqcos license activate --key QLOCK-XXXX-XXXX-XXXX-XXXX

[!NOTE] This activation command downloads a signed cryptographic license file and saves it to ~/.softqcos/license.qlicense. You can verify your local qubit limits and license status anytime by running:
softqcos license status

Step 2: Run the QCOS Daemon Locally

To process simulation jobs locally on your machine without transmitting any circuit data or secrets to the cloud, start the local QCOS API Daemon.

Option A: Execute via Python (Local Interpreter)

Run the FastAPI application locally using uvicorn:

uvicorn src.api.main:app --host 127.0.0.1 --port 8000

Option B: Execute via Docker (Official Container)

If you prefer containerized runtimes, deploy the official daemon container:

docker run -d -p 8000:8000 \
  -v ~/.softqcos:/root/.softqcos \
  sqtprodacr.azurecr.io/qcos-daemon:latest

Step 3: Point the CLI & SDK to Local API

Once the daemon is running on port 8000, instruct the QCOS CLI and SDK to route all actions to your local environment instead of the cloud gateway:

# Set the default API url to your local daemon
softqcos config set api_url http://localhost:8000

Step 4: Execute Local Workloads

A. Python SDK Workflows

Instantiate the QCOSClient (which auto-detects localhost and validates the local .qlicense file) and submit a job:

from softqcos_sdk import QCOSClient

# Initialize client (auto-connects to localhost:8000 and validates license)
client = QCOSClient()

# Submit circuit for local simulation using built-in Qiskit Aer
result = client.jobs.submit(
    qasm="""
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    creg c[2];
    h q[0];
    cx q[0], q[1];
    measure q -> c;
    """,
    shots=2048
)

print("Local simulation result counts:", result["counts"])

B. Command-Line Interface (CLI)

Submit QASM files directly from the shell for local processing:

softqcos circuits simulate --qasm-file meu_circuito.qasm --shots 1024

C. Claude Desktop MCP Server Integration

Expose the 62 QCOS tools directly to your AI assistants. Add the following config to your ~/.config/claude/claude_desktop_config.json file:

{
  "mcpServers": {
    "softqcos-mcp": {
      "command": "softqcos-mcp",
      "env": {
        "QCOS_API_URL": "http://localhost:8000"
      }
    }
  }
}

Note: Any MCP tool invocation will locally check your ~/.softqcos/license.qlicense entitlement and process the simulation on your workstation CPU/GPU.

Step 5: Easily Switch to QCOS Cloud

When you need to offload massive circuits to high-performance GPUs (LUMI) or physical QPUs in the cloud, simply change the API endpoint. Cloud runs will check your credit balance and deduct credits per shot:

# Route calls to the SoftQuantus Cloud Gateway
softqcos config set api_url https://api.softquantus.com

Hardware Acceleration & Providers (CPU/GPU/QPU)

The client binary allows complete configuration of where and how tasks are run.

1. Local CPU Simulation (Default)

When executing against the local daemon, simulations run on your host CPU. The worker uses the Qiskit Aer AerSimulator(method='statevector') backend automatically without any additional configuration.

2. Local GPU Simulation (NVIDIA CUDA)

If your workstation has an NVIDIA GPU and drivers configured, QCOS uses it automatically. If CUDA support is missing, it falls back to CPU. To enable GPU support inside the Docker daemon container, launch it with the --gpus all flag:

docker run -d -p 8000:8000 \
  --gpus all \
  -v ~/.softqcos:/root/.softqcos \
  sqtprodacr.azurecr.io/qcos-daemon:latest

3. Physical QPUs (BYOB — Bring Your Own Backend)

To execute workloads on physical hardware (IBM Quantum, AWS Braket, Azure Quantum) without routing credentials through SoftQuantus cloud, register your credentials locally. They are stored encrypted in ~/.softqcos/config.json.

Step 1: List Supported Providers

softqcos backends providers

Returns: ibm_quantum, aws_braket, azure_quantum, pasqal, iqm, etc.

Step 2: Save Credentials Locally

IBM Quantum:

softqcos backends add-ibm --token "YOUR_IBM_API_TOKEN"

AWS Braket:

softqcos backends add-braket --access-key "AWS_ACCESS_KEY" --secret-key "AWS_SECRET_KEY" --region "us-east-1"

Azure Quantum:

softqcos backends add-azure -s "SUBSCRIPTION_ID" -g "RESOURCE_GROUP" -w "WORKSPACE_NAME" -l "eastus"

Step 3: Execute on Target QPU

The credential save command returns a credential ID (e.g. cred_abc123). Submit your job directly to the QPU backend:

softqcos backends execute \
  --credential cred_abc123 \
  --backend ibm_osaka \
  --circuit bell_state.qasm \
  --shots 2048

​Step 1: Acquire and Activate Your License

​Step 2: Run the QCOS Daemon Locally

​Option A: Execute via Python (Local Interpreter)

​Option B: Execute via Docker (Official Container)

​Step 3: Point the CLI & SDK to Local API

​Step 4: Execute Local Workloads

​A. Python SDK Workflows

​B. Command-Line Interface (CLI)

​C. Claude Desktop MCP Server Integration

​Step 5: Easily Switch to QCOS Cloud

​Hardware Acceleration & Providers (CPU/GPU/QPU)

​1. Local CPU Simulation (Default)

​2. Local GPU Simulation (NVIDIA CUDA)

​3. Physical QPUs (BYOB — Bring Your Own Backend)

​Step 1: List Supported Providers

​Step 2: Save Credentials Locally

​Step 3: Execute on Target QPU