Hands-on Tutorial: Build a Secure Desktop Agent to Orchestrate Quantum Workflows with Claude Code

Hands-on Tutorial: Build a Secure Desktop Agent to Orchestrate Quantum Workflows with Claude Code

Hook: If you manage quantum experiments or prototype hybrid classical–quantum workflows, you know the pain: messy coordination between local simulators, cloud backends, and scattered results — all while needing to keep secrets and file access tight. In 2026, with tools like Claude Code and Cowork enabling powerful desktop agents, you can automate that orchestration — safely.

This tutorial shows how to build a sandboxed desktop agent (using Claude Code/Cowork) that coordinates local Qiskit simulations, submits jobs to a quantum cloud backend, aggregates results, and enforces security controls to limit access. You’ll get architecture guidance, concrete code snippets, a hardened Docker sandbox pattern, and operational controls for production-ready deployment.

The 2026 context: Why this matters now

Late 2025 and early 2026 brought fast adoption of developer-grade AI assistants that can access local files and run tools. Anthropic’s Cowork research preview and Claude Code extended autonomous capabilities to desktop users, enabling orchestration agents that actually run code and manage files locally. That unlocks productivity — but also increases attack surface. See recent incident and simulation work such as the agent compromise case study for why threat modeling matters.

At the same time, quantum toolchains have matured: Qiskit and its Aer/Runtime ecosystems are standard for local simulation, while cloud providers (IBM Quantum, AWS Braket, Azure Quantum) offer diverse hardware backends and runtime APIs. Hybrid workflows that prototype locally and then scale to cloud hardware are now a common pattern — exactly the problem a desktop agent can solve.

“Cowork and Claude Code bring agentic orchestration to the desktop. Combine that with a clear security posture, and you can safely automate end-to-end quantum workflows.”

What you’ll build (overview)

The agent we’ll construct does four things:

1. Inspect a requested quantum task and decide whether to run it locally (fast simulation) or submit it to cloud hardware.
2. Execute local Qiskit simulations (Aer or qiskit-ibm-runtime local simulator) and validate results.
3. Submit jobs to a cloud provider (example: IBM Quantum via qiskit-ibm-runtime) and track status.
4. Aggregate results into a structured report, store outputs in a sandboxed workspace, and log an auditable trail.

Security controls we'll add:

• Filesystem sandboxing (container with read-only mounts and allowlist)
• Network allowlist for cloud endpoints
• Least-privilege credentials using ephemeral tokens / scoped API keys — see patterns for short-lived credentials and edge datastore strategies in edge datastore strategies.
• Human-in-the-loop authorization for cloud job submission
• Audit logs and immutable result snapshots

Prerequisites

• macOS/Linux/Windows with WSL — a modern desktop running the Cowork desktop app or Claude Code runtime (research preview).
• Python 3.10+ (virtualenv recommended)
• Qiskit (qiskit, qiskit-aer, qiskit-ibm-runtime) or equivalent SDKs
• Container runtime (Docker or Podman) — pair container hardening with filesystem and storage reviews such as the distributed file systems review when you design workspace mounts.
• Access to a cloud quantum backend: IBM Quantum API key (or AWS Braket / Azure Quantum credentials)
• Anthropic developer access to use Claude Code/Cowork (experiment preview or API key)

Architecture and flow

High-level architecture:

• Cowork/Claude Code agent (sandboxed container) — runs orchestration logic and tool wrappers.
• Tool wrappers — small executable scripts exposed to the agent: local_sim.py, cloud_submit.py, aggregator.py.
• Local simulator — Qiskit Aer (or qiskit-ibm-runtime local simulator).
• Cloud backend — IBM Quantum (example) via qiskit-ibm-runtime client.
• Workspace — an isolated directory mounted read-only except for an output folder; ensure append-only and WORM characteristics when needed as discussed in storage reviews like this one.
• Audit store — append-only logs (WORM) and signed result snapshots — see guidance on audit trails in audit trail design.

Decision flow

Agent receives instruction (via Cowork UI or a file). It:

1. Parses the requested workload (circuit complexity, shots, noise requirements).
2. If the circuit is small (<n qubits or gate count threshold), run locally.
3. If hardware characteristics required (noise model, multi-shot calibration), prompt for human approval before cloud submission.
4. Submit to cloud using ephemeral credentials and return a signed results bundle.

Step 1 — Prepare the local workspace and container

Create a project directory and initialize a Python virtual environment. We’ll also prepare a Dockerfile that enforces sandboxing primitives.

mkdir quantum-agent && cd quantum-agent
python -m venv .venv
source .venv/bin/activate
pip install qiskit qiskit-ibm-runtime anthropic

Sample Dockerfile (hardened):

FROM python:3.11-slim

# Create unprivileged user
RUN groupadd -r agent && useradd -r -g agent agent
WORKDIR /home/agent

# Copy only app, keep secrets out of image
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Create workspace and set permissions
RUN mkdir /workspace && chown agent:agent /workspace
USER agent
VOLUME ["/workspace"]

# Drop capabilities in runtime (via docker run --cap-drop ALL)
CMD ["/bin/bash"]

Run container with hardened flags (example):

docker build -t quantum-agent:latest .

docker run --rm -it \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --read-only \
  -v $(pwd)/workspace:/workspace:rw \
  --env CLAUDE_API_KEY="${CLAUDE_KEY}" \
  --env IBM_API_KEY="${IBM_KEY}" \
  quantum-agent:latest

Notes:

• Keep API keys out of image; inject at runtime only as ephemeral environment variables. For patterns and policy enforcement on token usage see edge datastore and short-lived credential patterns.
• Use a read-only filesystem and only mount a writable /workspace folder with tight mode.

Step 2 — Tool wrappers: small, auditable helpers

The agent shouldn’t execute arbitrary shell commands. Instead, expose a small number of audited tool scripts with narrow responsibilities.

Example: local_sim.py — runs a Qiskit circuit on Aer and writes results to /workspace/output.json

#!/usr/bin/env python3
import json
from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator
from qiskit import transpile

# Simple example: input descriptor loaded from file
with open('/workspace/input.json') as f:
    desc = json.load(f)

qc = QuantumCircuit.from_qasm_str(desc['qasm'])
sim = AerSimulator()
compiled = transpile(qc, sim)
job = sim.run(compiled, shots=desc.get('shots', 1024))
res = job.result()
counts = res.get_counts()

out = {'counts': counts}
with open('/workspace/output.json', 'w') as f:
    json.dump(out, f)
print('DONE')

Example: cloud_submit.py — submits to IBM Quantum runtime using an ephemeral token

#!/usr/bin/env python3
import json
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler
import os

with open('/workspace/input.json') as f:
    desc = json.load(f)

service = QiskitRuntimeService(channel='ibm_quantum', token=os.environ.get('IBM_API_KEY'))
backend = service.get_backend(desc['backend'] or 'ibmq_qasm_simulator')

# For runtime programs, use the Runtime Client; simplified for example
sampler = Sampler(session=service.session(), backend=backend)
job = sampler.run(desc['circuits'], shots=desc.get('shots', 1024))
result = job.result()

with open('/workspace/cloud_output.json', 'w') as f:
    json.dump(result.to_dict(), f)
print('CLOUD_DONE')

These wrappers are small, easy to review, and can be code-signed. The agent only calls these scripts — it does not run arbitrary shell commands. Consider code-signing and verification patterns and store verification artifacts alongside signed reports; see audit trail design for related guidance.

Step 3 — Compose the Claude Code orchestration prompt & tool interface

Claude Code (via Cowork) shines when you present the agent as a set of capabilities plus a clear policy. You’ll register tools the agent can call: local_sim, cloud_submit, aggregate_results, and request_human_approval.

Example tool manifest (JSON) the agent provides to Claude Code:

{
  "tools": [
    {"name": "local_sim", "description": "Run Qiskit Aer simulation on provided QASM. Returns output.json"},
    {"name": "cloud_submit", "description": "Submit job to cloud quantum backend. Requires human approval."},
    {"name": "aggregate", "description": "Aggregate outputs into a signed report file."},
    {"name": "request_approval", "description": "Trigger a human-in-the-loop approval. Returns APPROVED/REJECTED."}
  ],
  "policies": {
    "allow_fs_paths": ["/workspace/input.json", "/workspace/output.json"],
    "deny_commands": ["/bin/rm", "/usr/bin/ssh"]
  }
}

Agent prompt template (concise):

Task: Execute a quantum workload described in /workspace/input.json

1) Inspect input.json and decide: local_sim or cloud_submit.
2) If local_sim: call tool local_sim.
3) If cloud_submit: call request_approval. If APPROVED, call cloud_submit.
4) After results, call aggregate to build signed report.

Security: do not access files outside allowed paths. Log every tool invocation.

Use the Claude Code SDK to create an agent with these tool bindings and policies. Exact API names differ between Anthropic releases; the pattern is consistent: register tools, provide a system prompt, and expose the agent within Cowork so it can run inside the sandbox. For compliance and policy-as-code integration, consider patterns from CI compliance automation.

Step 4 — Human-in-the-loop approval flow

Cloud submissions should require an explicit human ok. Implement a small approval service that listens on a secure channel (e.g., a local system tray notification via Cowork or an authenticated web UI) and writes /workspace/approval.json with APPROVED or REJECTED.

# Pseudocode for request_approval tool
prompt user with summary: backend, estimated runtime, cost estimate
if user clicks APPROVE: write {'approval': 'APPROVED'} else write {'approval': 'REJECTED'}

Make sure the approval UI requires a second factor or a desktop session lock to avoid accidental approvals — tie approvals into your audit trail and signed logs so that every cloud submission has a verifiable human attestation, as recommended in audit trail best practices.

Step 5 — Aggregation, signing, and audit logs

After results are produced, aggregate outputs and create a signed bundle. Use a local signing key kept in an OS-protected keystore (or hardware-backed key, like Secure Enclave / TPM) to sign the report.

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

# load private key from keystore (example stub)
with open('/run/keys/agent_key.pem', 'rb') as kf:
    priv = serialization.load_pem_private_key(kf.read(), password=None)

with open('/workspace/output.json') as f:
    payload = f.read()
sig = priv.sign(payload.encode('utf-8'), padding.PSS(...), hashes.SHA256())

with open('/workspace/report.json', 'w') as f:
    json.dump({'payload': json.loads(payload), 'signature': base64.b64encode(sig).decode()}, f)

Write audit logs to an append-only file or forward them to a secure SIEM. Include timestamps, tool calls, and who approved cloud submissions. For signed outputs and append-only storage recommendations, see storage and audit guidance such as the distributed file systems review and audit trail design.

Step 6 — Example run: Grover’s algorithm end-to-end

Create an input descriptor /workspace/input.json

{
  "qasm": "// QASM for a small Grover circuit",
  "shots": 2048,
  "preferred_backend": "local"
}

Agent flow:

1. Claude Code parses input.json and sees preferred_backend local → calls local_sim tool.
2. local_sim runs Qiskit Aer, produces output.json.
3. Agent calls aggregate; aggregator signs the report and writes report.json.

For a cloud run, preferred_backend would be a named IBM device. Agent would trigger request_approval; after approval, call cloud_submit which uses ephemeral token and writes cloud_output.json. Aggregator then merges local and cloud outputs into a final signed artifact.

Security hardening checklist

• Sandbox Process: Run the agent inside an unprivileged container with capabilities dropped and seccomp/AppArmor in place — pair with container hardening and filesystem reviews such as this distributed file systems review.
• Filesystem Scope: Mount only the workspace folder writable and disallow access to /etc, /home, or SSH keys.
• Network Filtering: Restrict outbound DNS/IPs to trusted cloud endpoints using iptables or eBPF allowlists.
• Credential Hygiene: Use ephemeral scoped tokens (short-lived), not long-lived API keys. Use OIDC or cloud STS where possible — see short-lived token patterns in edge datastore strategies.
• Tool Allowlist: Agent can only call vetted helper scripts. No shell or subprocess execution of arbitrary commands.
• Human Approvals: Require multi-factor confirmation before any cloud submission or credential use.
• Code Signing: Sign helper scripts and verify signatures at startup.
• Audit & Monitoring: Forward logs to SIEM, store signed reports with checksums in WORM storage. For audit and signing approaches, consult audit trail design.

Operational tips and scaling

Start by limiting your agent’s scope to a single researcher and one cloud backend. As adoption grows, introduce:

• Role-based access control (RBAC) for who can request runs and who can approve.
• Quota enforcement to limit cost exposure when using cloud hardware.
• Job batching and result comparison features for reproducibility across simulators and hardware.
• Automated regression tests: run reference circuits nightly to validate simulator parity with backends. Consider scheduling and tooling integration patterns covered in developer tooling reviews such as developer CLI reviews.

Recent trends (2025–2026) that should influence your design

Several trends in late 2025 and early 2026 affect agent design:

• Desktop agents gained file access capabilities (Anthropic Cowork), driving the need for stricter sandboxing and process-level controls.
• Quantum cloud providers improved runtime APIs and ephemeral credential support, making least-privilege submissions much easier.
• Hybrid workflows are standard: developers prototype locally with Qiskit Aer and then run calibration-sensitive jobs in the cloud for final results.
• Auditable reproducibility became a compliance requirement for some research and regulated industries; signed results and WORM storage matter — see append-only and distributed storage guidance in distributed file systems.

Advanced strategies

If you want to push further:

• Policy-as-code: encode allowed actions in a policy engine (OPA/Rego) that Claude Code consults before making decisions — connect this to wider CI governance patterns such as automated compliance checks.
• Zero-trust local networking: use mutual TLS for internal tool calls and an internal PKI for agent identity.
• Attestation: use TPM/SE attestation to ensure the agent runs on trusted hardware and verify it before releasing keys — these approaches complement threat simulation exercises like the autonomous agent compromise case study.
• Hybrid orchestration: combine local agents with a central orchestrator to manage distributed experiments and aggregate telemetry.

Common pitfalls

• Exposing long-lived credentials in the container image — keep keys out of images and use short-lived tokens.
• Allowing the agent to spawn arbitrary shell commands — restrict to small, reviewed tools.
• Not requiring human approvals for potentially costly or sensitive cloud runs.
• Failing to collect cryptographic evidence of results — unsigned outputs are harder to trust later; see audit trail guidance at audit trail design.

Checklist before production rollout

1. Threat model the agent’s capabilities (file access, network egress, APIs) — include red-team runs modeled after incident simulations such as this case study.
2. Implement least-privilege credentials and rotate them automatically.
3. Harden the container runtime and enable logging/alerting.
4. Run red-team tests to ensure the agent cannot be coerced into exfiltrating secrets.
5. Document operator procedures and train approvers on the human-in-the-loop UI.

Conclusion and actionable takeaways

By 2026, desktop agents like those enabled by Claude Code and Cowork make it practical to orchestrate hybrid quantum workflows locally and in the cloud. The risks are real, but they’re manageable with a defensive architecture: sandbox the agent, expose only vetted tools, use ephemeral credentials, require human approvals for cloud jobs, and sign results for auditability.

Actionable steps to get started right now:

• Prototype the agent in a local Docker sandbox and use small tool wrappers for simulation and submission.
• Enforce a clear allowlist for file paths and network endpoints.
• Wire in a human approval channel before any cloud hardware submission.
• Sign and store every results bundle in append-only storage with cryptographic verification.

These steps keep you productive while reducing operational and security risk as desktop agents become part of standard developer tooling for quantum computing.

Resources & next steps

• Qiskit documentation and examples (qiskit.org)
• IBM Quantum and qiskit-ibm-runtime guides
• Anthropic Claude Code and Cowork research preview pages (for SDK and agent integration patterns)
• Best practices for container hardening (CIS Docker Benchmark) — pair with storage and audit considerations from distributed file systems review.

Call to action

Ready to build your own secure Claude Code desktop agent? Start with the sample Dockerfile and tool wrappers above, spin up a sandbox, and run a local Qiskit circuit. If you want, share your agent design or a snippet of your tool wrapper in the qubit365 community — we’ll review it and suggest security hardening or scalability improvements.

Related Reading

• Case Study: Simulating an Autonomous Agent Compromise — Lessons and Response Runbook
• Designing Audit Trails That Prove the Human Behind a Signature — Beyond Passwords
• Review: Distributed File Systems for Hybrid Cloud in 2026 — Performance, Cost, and Ops Tradeoffs
• Edge Datastore Strategies for 2026: Cost-Aware Querying, Short-Lived Certificates, and Quantum Pathways
• VistaPrint Coupons: Best Codes for 2026 Small-Business Marketing
• From Folk Roots to Global Pop: A Listening Guide to BTS’ Next LP
• Best MicroSD Cards for Switch 2: Why the Samsung P9 256GB Express Is a Smart Pick
• CES 2026 Tech That Belongs in Your Dressing Room (and How to Use It)
• Why Circadian Lighting Matters for Care Facilities — Advanced Strategies for 2026