FAQ

Getting started

What is QubitHub?

QubitHub is developer infrastructure for quantum computing. Discover, share, and execute quantum circuits — like GitHub, but purpose-built for quantum algorithms.

Do I need a quantum computer?

No. QubitHub includes a built-in simulator that handles circuits up to roughly 20 qubits efficiently. Larger circuits may require hardware backends (planned for a future release) or specialized simulation techniques.

Which quantum frameworks are supported?

Qiskit (IBM), PennyLane (Xanadu), Cirq (Google), Amazon Braket (AWS), and OpenQASM 3 (an open circuit description standard). Each circuit declares its framework in its qubithub.toml manifest, and some circuits offer multi-framework implementations.

Note

The built-in simulator supports Qiskit, PennyLane, and Cirq execution. Braket and OpenQASM 3 circuits can be described, shared, and versioned on QubitHub, but are not yet executable in the sandbox. Hardware and additional simulator backends are on the roadmap.

How do I install the CLI?

pip install qubithub-sdk

This installs both the Python SDK and the qubithub CLI (plus the qhub alias). Requires Python 3.11 or later. See the CLI Quickstart for a full walkthrough.

Alternative installers

You can also install with uv, pipx, or conda — any Python package manager that pulls from PyPI will work.

How do I log in?

Interactive login:

qubithub login

For CI/CD or non-interactive environments, pass an API key:

qubithub login --api-key qh_abc123...

You can also set the QUBITHUB_API_KEY environment variable.

Circuits

How do I publish a circuit?

1. Run qubithub circuits init <name> --framework <framework> to scaffold a project.
2. Write your circuit code in circuit.py (must export a create_circuit() function).
3. Fill in qubithub.toml with accurate metadata.
4. Run qubithub circuits push — the CLI validates your manifest and uploads the circuit.

See the Contributing Circuits guide for the full quality checklist.

What is qubithub.toml?

The circuit manifest file. It declares your circuit’s metadata — name, framework, qubit count, gates, execution defaults, and more. QubitHub uses a 3-tier progressive complexity model:

• Tier 1 (minimal): name, title, type, framework, entry point, qubits (number of quantum bits used)
• Tier 2 (standard): adds description, tags, difficulty, execution config, educational metadata
• Tier 3 (advanced): adds hardware constraints, parameters, reproducibility, references

See the qubithub.toml Reference for the full specification.

What domains does QubitHub cover?

QubitHub covers all quantum computing domains: algorithms, QML, optimization, chemistry, error correction, quantum information, simulation, cryptography, communication, and hardware benchmarking.

How does circuit naming work?

Circuits follow a namespace pattern: <owner>/<name> (e.g., QubitHub/bell-state or alice/grover-3q). Names must be lowercase with hyphens only, up to 100 characters.

Can I fork a circuit?

Yes. Use qubithub circuits fork <owner>/<name> to create your own copy under your namespace. The fork links back to the original for provenance. You can then modify and push changes independently — each fork has its own version history.

How does circuit versioning work?

Each time you push changes with qubithub circuits push, a new version is created. You can view version history and access any prior version. Circuit versions are immutable once published.

Execution

What happens when I execute a circuit?

Your code runs in an isolated Docker sandbox with no network access, a read-only filesystem, and strict resource limits. The simulator runs your circuit many times (called “shots”) and tallies how often each possible outcome occurs. For example, a Bell state circuit might return {"00": 512, "11": 512}, meaning outcomes 00 and 11 each appeared about half the time out of 1,024 shots.

What are the execution limits?

Limit	Default	Maximum
Timeout	30 seconds	300 seconds
Shots	1,024	100,000
Code length	—	5,000 characters

The sandbox also enforces memory (512 MB), CPU (1 core), and process (64 PIDs) limits.

Tip

Shots are the number of times a circuit is executed and measured to build a statistical distribution. More shots give more accurate probability estimates — 1,024 is a common default, and 10,000+ is typical for publication-quality results.

Which Python packages are available in the sandbox?

Qiskit, Qiskit Aer, PennyLane, Cirq, NumPy, SciPy, Matplotlib, and Python standard library modules (math, cmath, random, json, collections, itertools, functools, typing, dataclasses). Other packages are not available — the sandbox has no network access to install them.

Why was my code blocked?

The sandbox performs static analysis before execution. Code is rejected if it uses:

• Blocked imports (subprocess, os, sys, ctypes, socket)
• Dangerous builtins (eval, exec, compile, open, __import__)
• Dynamic attribute access (getattr, setattr — use direct attribute access like obj.attr instead)
• File I/O operations (e.g., numpy.loadtxt, matplotlib.savefig)

This is defense-in-depth on top of the Docker isolation. See Troubleshooting for specific error messages.

API keys & authentication

What’s the difference between JWT tokens and API keys?

JWT tokens are short-lived (15 minutes) and best for interactive sessions — the CLI handles refresh automatically. API keys are long-lived and scoped — use them for scripts, CI/CD, and automation. API keys use the qh_ prefix.

See the Authentication guide for the full details.

How do I create an API key?

qubithub keys create --name "CI pipeline" --scopes circuit:read,runs:submit --expires 90

Available scopes:

Scope	Grants
circuit:read	Browse and download circuits
circuit:write	Create, update, and delete circuits
runs:submit	Execute circuits
dataset:read	Browse and download datasets
dataset:write	Create, update, and delete datasets
org:read	View organization details
org:write	Manage organization settings and members
repo:read	Read repository metadata
repo:write	Manage repository settings

How many API keys can I have?

During beta, each account can create up to 2 API keys. Higher limits will be available on paid tiers after general availability.

Organizations

Can I create a team or organization?

Yes. Organizations provide shared namespaces for circuits, datasets, and spaces. Members have role-based permissions (Owner, Admin, Member). See the Organizations guide.

Pricing & limits

Is QubitHub free?

Yes, during beta. A free tier will always exist. The current beta limits:

Resource	Free tier
Circuits	10
Datasets	5
Spaces	2
Runs	100 / month
Compute time	5 minutes / month
Storage	100 MB
API rate	60 requests / minute
API keys	2

Pro and Enterprise tiers with higher limits are planned. All circuits and data created during beta will be preserved when we transition to general availability.

Comparisons

How is QubitHub different from IBM Quantum or AWS Braket?

IBM Quantum and AWS Braket focus primarily on hardware access and managed execution environments. QubitHub focuses on a different layer: discovery, collaboration, and reproducibility of quantum algorithms across frameworks — more like GitHub for quantum code than a hardware provider.

How is QubitHub different from sharing circuits on GitHub?

GitHub stores code. QubitHub adds one-click execution, structured metadata (qubithub.toml), circuit visualizations, versioning, a quantum-native search and discovery experience, and benchmark comparisons — all purpose-built for quantum workflows.

What’s next?

• Having trouble? Check the Troubleshooting guide.
• New to QubitHub? Start with the CLI Quickstart or the Web UI Guide.
• Ready to publish? Follow the Contributing Circuits guide.
• Need API details? See the API Reference and Authentication guide.
• Still stuck? Email us at support@qubithub.co.