Skip to content

Gear Specifications

Important: This page provides only a brief overview. For complete and authoritative information, always refer to the official Gear Specifications on GitLab. Developers should consult the official documentation when building gears.

What are Flywheel Gears?

Flywheel gears are containerized applications that process data within the Flywheel platform. Built on Docker, they follow a standardized structure that enables seamless integration with Flywheel's ecosystem.

Essential Components

Every gear requires three key components:

  1. manifest.json - Defines metadata, inputs, and configuration
  2. Dockerfile - Specifies the container build process
  3. Run script - Contains the executable code

The manifest.json file is particularly critical as it defines how Flywheel interacts with your gear, including:

  • Basic metadata (name, version, author)
  • Input file specifications
  • Configuration parameters
  • Environment variables
  • Execution command

Classification Validation

Gears can set classification values on output files by writing a .metadata.json file to the output directory. Flywheel validates these classification values against the defined classification schema for the file's modality.

Starting in Flywheel 21.4.0, if a gear sets a classification value on an output file via .metadata.json that does not match the schema, Flywheel logs a warning in the job log but allows the job to complete. In Flywheel 23.0.0, invalid classification output will cause the job to fail.

Ensure your gear only writes classification values that conform to the Flywheel classification scheme. Monitor the Jobs Log for classification validation warnings on your gear runs.

Execution Environment

When running, gears operate in a standardized directory structure:

  • /flywheel/v0/ - Main working directory
  • /flywheel/v0/input/ - Input files
  • /flywheel/v0/output/ - Output destination
  • /flywheel/v0/config.json - Runtime configuration
  • /flywheel/v0/manifest.json - Gear manifest

Resources for Gear Developers