This guide walks you through installing the QCOS quantum operating system and the SynapseX Console on your local machine from absolute scratch. We adopt an Open-Core / Hybrid Cloud model:

Local simulation (using CPU/GPU) is completely free and executes locally on your hardware.
Cloud executions (routing to QPUs like IBM Quantum, IonQ, Rigetti, or HPC clusters like LUMI) submit jobs securely to our cloud endpoints.

1. Prerequisites Setup

Before installing QCOS, ensure you have the required runtimes installed for your operating system.

macOS

Homebrew (recommended): Open terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Python: QCOS requires Python 3.10 to 3.13. Install it using Homebrew:
brew install python@3.11
Node.js (for npm fallback):
brew install node

Linux (Ubuntu/Debian)

Python: Run the following commands to install Python 3.11 and pip:

sudo apt-get update
sudo apt-get install -y python3.11 python3-pip python3-venv

Node.js (for npm fallback):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows

Python:
- Download the official installer for Python 3.11+ from python.org.
- CRITICAL: During installation, check the box that says “Add Python to PATH” before clicking install.
Node.js: Download and run the LTS installer from nodejs.org.

2. CLI Installation

You can install the softqcos command-line interface (CLI) using automated script installers or by manually downloading the compiled standalone binary.

Option A: Automated Terminal Install (macOS / Linux)

Run the following command in your terminal. This script automatically detects your operating system and architecture, downloads the correct precompiled binary, and installs it to /usr/local/bin/softqcos:

curl -fsSL https://synapsex.ai/install | bash

Option B: Automated PowerShell Install (Windows)

Open PowerShell as an Administrator and execute:

iwr -useb https://synapsex.ai/install.ps1 | iex

Option C: Manual Binary Installation (All OS)

If you prefer not to use the automated installers, or are operating in an offline environment, you can download the standalone compiled binaries directly.

Note on Binary Naming: The QCOS CLI and SynapseX agents share the same high-performance, compiled backend. Therefore, the binaries downloaded from our blob storage are prefixed with synapsex. When activating them locally, you will rename the executable to softqcos for use with the quantum tooling.

OS / Architecture	Download URL
macOS Apple Silicon (arm64)	Download Binary
macOS Intel (x64)	Download Binary
Linux arm64	Download Binary
Linux x64	Download Binary
Windows x64	Download Binary

Activating Manual Binaries (macOS / Linux):

Move the downloaded binary to a directory in your system path (e.g., /usr/local/bin/):
sudo mv synapsex-darwin-arm64 /usr/local/bin/softqcos
Grant executable permissions:
sudo chmod +x /usr/local/bin/softqcos
Verify the installation:
softqcos --version

Activating Manual Binaries (Windows):

Move the downloaded synapsex-win32-x64.exe to a directory of your choice, e.g., C:\Program Files\softqcos\softqcos.exe.
Add that directory to your User Environment Variables Path list.
Open a new PowerShell terminal and verify:
softqcos --version

3. Python SDK & CLI Installation

To install or upgrade the QCOS Python SDK and CLI on your workstation without dependency conflicts:

python -m pip install --upgrade pip
python -m pip install --upgrade \
  https://sqtprodsa.blob.core.windows.net/downloads/softqcos_sdk-3.5.0-py3-none-any.whl \
  https://sqtprodsa.blob.core.windows.net/downloads/softqcos-3.5.0-py3-none-any.whl

4. Persisting Environment Variables

To authorize CLI, SDK, and local worker actions, you must configure your API keys and validation mode. These variables must be set correctly, or commands will return unauthorized errors.

macOS & Linux (Bash/Zsh)

To ensure these variables persist across system restarts, add them to your shell profile configuration (~/.zshrc for zsh, or ~/.bashrc for bash):

# Open profile file in editor
nano ~/.zshrc

# Add the following lines at the end of the file:
export QCOS_API_URL="https://api.softquantus.com"
export QCOS_API_KEY="sqt_live_your_key"
export QUANTUMLOCK_LICENSE_PATH="$HOME/.softqcos/license.qlicense"
export QUANTUMLOCK_VALIDATION_MODE="hybrid"

# Save and exit (Ctrl+O, Enter, Ctrl+X)
# Reload profile config:
source ~/.zshrc

Windows (PowerShell)

To set environment variables for the current PowerShell session:

$env:QCOS_API_URL="https://api.softquantus.com"
$env:QCOS_API_KEY="sqt_live_your_key"

To persist these variables permanently on Windows:

Open PowerShell and run:

[Environment]::SetEnvironmentVariable("QCOS_API_URL", "https://api.softquantus.com", "User")
[Environment]::SetEnvironmentVariable("QCOS_API_KEY", "sqt_live_your_key", "User")
[Environment]::SetEnvironmentVariable("QUANTUMLOCK_LICENSE_PATH", "$env:USERPROFILE\.softqcos\license.qlicense", "User")
[Environment]::SetEnvironmentVariable("QUANTUMLOCK_VALIDATION_MODE", "hybrid", "User")

Restart any open terminal windows to apply the changes.

5. Next Steps

Now that your paths and tools are configured, head over to the Quick Start guide to run your first circuit, or read the Hybrid Cloud guide to understand how to switch between local simulations and cloud hardware.

​1. Prerequisites Setup

​macOS

​Linux (Ubuntu/Debian)

​Windows

​2. CLI Installation

​Option A: Automated Terminal Install (macOS / Linux)

​Option B: Automated PowerShell Install (Windows)

​Option C: Manual Binary Installation (All OS)

​Activating Manual Binaries (macOS / Linux):

​Activating Manual Binaries (Windows):

​3. Python SDK & CLI Installation

​4. Persisting Environment Variables

​macOS & Linux (Bash/Zsh)

​Windows (PowerShell)

​5. Next Steps