Capsules
Capsules are reproducible snapshots of quantum computations. They bundle a script, execution parameters, backend configuration, and results into a single auditable package. Capsules are designed for reproducibility, verification, and sharing.
Creating a capsule
From a completed job
The most common way to create a capsule is from a completed job. On the job results page, click Create Capsule. The platform packages:
- The script and its parameters
- The backend used
- The full result JSON
- Timing and cost metadata
You can optionally seal the capsule immediately on creation.
Manual creation
Create a capsule via POST /api/capsules/create with a workflow definition, description, and optional configuration (tags, budget limits, retention period, regulatory framework, target backends).
Manual capsules start in draft state.
Lifecycle states
Capsules progress through a defined lifecycle:
| State | Description | Editable? |
|---|---|---|
| draft | Initial state. Capsule metadata can be modified. | Yes |
| runnable | Capsule has been imported from a job and is ready to execute. | No (metadata locked) |
| sealed | Immutable. Results are finalized, digests are computed. Cannot be modified or deleted. | No |
| published | Sealed capsule shared to the community. | No |
Sealing
Sealing a capsule (POST /api/capsules/{id}/seal) locks it permanently. Requirements:
- The capsule must have task execution records
- The capsule must have a results artifact
- An exit code and optional exit message must be provided
Once sealed, the capsule records cryptographic digests of its contents, the sealing user, and the seal timestamp.
Publishing
A sealed capsule can be published to the community (POST /api/capsules/{id}/publish). Provide a title, description, optional readme, license, category, and tags. The capsule becomes publicly discoverable.
Execution modes
Capsules support two execution modes:
Verify mode
Re-runs the capsule using the exact same parameters and backend as the original execution. This is used to confirm that results are reproducible. Only capsules created from jobs support verify mode.
Template mode
Runs the capsule with different parameters or on a different backend. You provide new parameters and a target backend. This lets you use a capsule as a reusable template for parameter sweeps or cross-backend comparisons.
Both modes create a new job linked to the capsule, with full cost estimation and budget checks.
Auditing
All capsule operations (create, update, seal, execute, delete) are logged to an audit trail with:
- User who performed the action
- Timestamp
- Previous and new state
- Additional metadata (parameters, cost, backend)
Deleting capsules
Only draft and runnable capsules can be deleted. Sealed and published capsules are immutable and cannot be removed. Only the capsule owner can delete.