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.

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

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

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 23.0.0, if a gear sets a classification value on an output file via .metadata.json that does not match the schema, the job fails. The job log records an error in this format:

1
Error: Job failed because file "<file name>" has an invalid classification: The following aspect keys do not adhere to the classification schema: [<invalid keys>]

In Flywheel 21.4.0 through 22.x, Flywheel logged only a warning in the job log and allowed the job to complete.

Ensure your gear only writes classification values that conform to the Flywheel classification scheme. To find gear runs that failed for this reason, check the job log in the Jobs Log.

Resources for Gear Developers