cytario-app-sdk

A small CLI for registering Cytario analysis applications in an OCI Distribution v1.1 registry (e.g. Harbor 2.13+).

Cytario's "app catalog" is our concept, not the registry's: an analysis application is a container image plus a metadata document (the app-definition) that declares the app's parameter schema and input/output data roles. The SDK attaches the app-definition to the container image as an OCI Image Format annotation (org.cytario.appdef.v1) on the image manifest, then PUTs the manifest back under its original tag. Because the annotation is part of the manifest content, the manifest's immutable content digest binds the definition to the exact image — pinning the image by digest also pins the definition. The Cytario runtime fetches the manifest via GET /v2/<name>/manifests/<ref> and reads the definition from its annotations; no Harbor-specific API is used.

Application access (who may see/run an app, who may edit its saved configs) is not part of the app-definition. Entitlement is governed by the catalog connection's access scope on the Cytario side, not by anything carried in the registry image.

Install

pip install cytario-app-sdk
cytario-app-sdk --help

Or with uv:

uv tool install cytario-app-sdk

Quick start

cytario-app-sdk --registry https://harbor.example.com \
  --user 'robot$cytario-catalog' \
  --secret <robot-token> \
  register examples/cellseg.yaml

Connection settings (registry endpoint, user, secret) can be supplied on the command line or via a YAML config file consumed by typer-config:

# cytario-app-sdk.yaml
registry: https://harbor.example.com
user: robot$cytario-catalog
secret: <robot-token>

cytario-app-sdk --config cytario-app-sdk.yaml register examples/cellseg.yaml

Validate an app-definition without pushing anything:

cytario-app-sdk --config cytario-app-sdk.yaml register --dry-run examples/cellseg.yaml

Registering an app

# examples/cellseg.yaml
schemaVersion: 1
name: cellseg
display: Cell Segmentation
description: Runs Cellpose on a 16-bit OME-TIFF.
image:
  repository: cytario/cellseg
  tag: "1.0.0"
parameterSchema:
  type: object
  properties:
    diameter:
      type: number
      default: 30
  required: []
inputRoles:
  - name: image
    mediaTypes:
      - image/tiff
outputRoles:
  - name: segmentation
    mediaTypes:
      - application/vnd.cytario.label-mask

register fetches the container image manifest (by tag or digest), builds the app-definition document, attaches it as the org.cytario.appdef.v1 annotation on the manifest, and PUTs the manifest back under the original tag. The new manifest digest (returned by the registry) pins both the image and the definition. The Cytario runtime reads the annotation back via GET /v2/<name>/manifests/<ref>; no Harbor-specific calls are made.

Development

This project uses uv and targets Python 3.10+.

uv sync                          # install deps into .venv
uv run cytario-app-sdk --help    # run the CLI
uv run ruff check --fix && uv run ruff format
uv run pytest

See CONTRIBUTING.md for the full contributor guide and the Releases page for release history. Versions are cut automatically with python-semantic-release — in no-commit mode, so no release commits land on main.

License

Released under the MIT License. By contributing, you agree that your contributions will be licensed under the MIT License.