Anatomy of a BioChef tool

What it covers

Recipes declare tools/workflows; Hub validates, signs, and bundles them for Registry.

Key behaviors

• Schema validation against the BioChef recipe schema; each built tool is run on the example input of its data types.
• Builds with Emscripten/biowasm (WASM) or as a native tarball; generates SBOM and SLSA attestation.
• Pushes the bundle to the BioChef Registry, signs it with keyless cosign and attaches SLSA provenance, then republishes the signed index.json catalogue.

Practical tips

• Author YAML in biochef-recipes under recipes/<tool>/biochef.yaml; validate before opening a PR.
• Keep inputs/outputs typed; CI runs each tool on the example input of its data types.
• The reusable workflows live in biochef-hub/.github/workflows/validate-recipes.yml (PR validation) and publish-recipes.yml (build + publish on merge).

apiVersion: v1
id: app.biochef.wgsim
name: wgsim
description: Simulate NGS reads from a reference FASTA.
version: 0.3.1-bc.1
homepage: https://github.com/lh3/wgsim
license:
  spdx: MIT
  files: [wgsim.c]
maintainers:
  - name: Biochef
source:
  repo: https://github.com/lh3/wgsim
  commit: "a12da3375ff3b51a5594d4b6fa35591173ecc229"
  version: "0.3.1"
status: experimental
build:
  wasm:
    strategy: emscripten
    emscripten:
      emscriptenVersion: 4.0.18
      buildScript: build-wasm.sh
  native:
    buildScript: build-native.sh
    buildTools: [gcc]
runtime:
  modes: [wasm, native]
operations:
  - id: wgsim.simulate
    name: Simulate (wgsim)
    category: Genomic Operations
    bin: wgsim
    description: Simulate paired-end reads
    io:
      inputs:
        - { name: ref, types: [FASTA], mode: file }
      outputs:
        - { name: out1, types: [FASTQ], mode: file, flag: "", filename: "read1.fq" }
        - { name: out2, types: [FASTQ], mode: file, flag: "", filename: "read2.fq" }
    parameters:
      - { name: num_pairs, type: integer, flag: -N }
      - { name: seed, type: integer, flag: -S }

What it covers

The BioChef Registry, live at registry.biochef.app, stores signed OCI artifacts (bundle.json + WASM/JS layers + SBOM) and the signed index.json that lists every published tool by digest.

Key behaviors

• Each tool version is content-addressable: pulled by digest, not by mutable tag.
• The Hub signs every bundle with keyless cosign, and signs the top-level index.json catalogue (ES256) only after verifying those signatures and the SLSA provenance.
• WASM and JS assets are served as plain HTTPS so the browser app can stream them.

Practical tips

• Treat each version as immutable; promote new builds, never overwrite digests.
• The browser checks the catalogue signature and every digest itself before running a tool; cosign and SLSA are verified by the Hub before the catalogue is signed.
• Use the signed index.json as the source of truth for what is publishable.

What it covers

The BioChef web app, a static React/Webpack SPA, runs every published bioinformatics tool entirely in the browser via WebAssembly. Has a Tools page for single-tool runs and a Workflow page for DAG-style chains.

Key behaviors

• Loads tools by digest from the BioChef Registry; aioli/biowasm boots them in a Web Worker.
• Before showing any tool, the app checks the catalogue’s signature against a public key pinned in the app and keeps only entries that passed the publication checks; before running one, it checks the SHA-256 of the OCI manifest, the bundle, the JavaScript and the WebAssembly. A tool that fails is not offered.
• Detects input data type (FASTA, FASTQ, Multi-FASTA, DNA, RNA, amino acids, BAM, SAM, CRAM, VCF, BCF, BED, GFF, JSON, LIST, …) and filters compatible tools.
• DAG editor re-executes downstream steps on parameter change; workflows can be exported and imported as JSON.

Practical tips

• The BioChef SPA’s bundled GTO modules are built with Emscripten 3.1.65 (rebuild locally with npm run build-wasm). Hub CI compiles new recipes with Emscripten 4.0.18.
• Outputs stream live to the Output panel; inspect intermediate steps without re-running the whole pipeline.
• The whole app is static. Host it from any CDN or GitHub Pages.

{
  "runtime": "wasm",
  "tool": "gto.fastq.to.fasta@1.6.3-bc.1",
  "verify": true,
  "source": "https://registry.biochef.app/.../sha256:..."
}