Developers

For Developers

Write a YAML recipe, push it through the Hub CI, and your tool ends up signed in registry.biochef.app and runnable from the BioChef web app.

Quickstarts

Three ways in

Pick a path and get to a running BioChef in under five minutes.

Step 01 · Author

Write a new recipe

Author a YAML recipe in your own repo. The Hub workflow validates, signs, and publishes it for you.

  1. 1Fork biochef-recipes and create recipes/<tool>/biochef.yaml.
  2. 2Run hub validate on it. CI also runs each built tool on the example input of its data types, so declare the types carefully.
  3. 3Open a PR. The reusable Hub workflow runs validate → build → test → SBOM. After merge it publishes, signs with cosign, attaches SLSA provenance and republishes the signed catalogue.
ieeta-pt/biochef-recipes

Step 02 · Run

Run the BioChef app locally

Clone the SPA, install deps, and serve it with the dev server. No backend required.

  1. 1git clone https://github.com/ieeta-pt/biochef-app and npm install.
  2. 2(Optional) install Emscripten 3.1.65 and run npm run build-wasm to rebuild the SPA's bundled GTO modules from source. Hub CI uses Emscripten 4.0.18 for new recipes.
  3. 3npm start and open http://localhost:8082.

Or docker compose -f docker-compose.dev.yml up: the app plus an empty local registry. The tools profile adds the Hub to publish recipes into it.

ieeta-pt/biochef-app

Step 03 · Inspect

Pull a signed bundle

Tools live in the BioChef Registry as content-addressable OCI bundles. The web app fetches them by digest at runtime; you can pull them with ORAS and verify them with cosign.

  1. 1Resolve a tool by digest in the signed index.json catalogue.
  2. 2Pull the OCI bundle (bundle.json + WASM/JS layers + SBOM) with ORAS.
  3. 3Verify the bundle's cosign signature and SLSA provenance; the web app itself checks the catalogue signature and every digest before running it.
Hub CLI on GitHub

Running tools next to the data instead? biochef-agent: ./run.sh, configured through example.env.

Snippets

What the code looks like

A recipe in YAML, the Hub CLI run, and an exported workflow.

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 }
yaml42 lines