Submit a scaffold

A scaffold submission is a repository bundle whose root contains card.yaml. The Hub validates and stores the card and referenced files, but it does not import or execute a submitted controller.

This flow publishes metadata and source artifacts. To run the scaffold locally, its controller class must also exist in an installed/local Python package or be loadable from a file spec supported by the card loader. See Write your own scaffold for that implementation step.

1. Lay out the repository

my_scaffold/
├── card.yaml
├── README.md
├── config.yaml
└── my_scaffold.py

An illustrative card:

name: my_scaffold
display_name: My Scaffold
organization: my-lab
type: test_time_search
family: search_baseline
summary: "A custom Galapagos search scaffold."
license: Apache-2.0
controller: my_package.MyScaffold
components:
  population: {kind: keep_all}
  selection_policy: {kind: custom_policy}
  prompt_builder: {kind: default_prompt}
  proposer: {kind: diff}
  evaluator: {kind: task}
  memory: {kind: none}
assets: [README.md, config.yaml, my_scaffold.py]

controller is inert metadata on the Hub. Naming a class here does not install it and does not make the hosted runners execute it. Include source files as assets so reviewers can inspect/download them, and install the controller package before trying to load the card locally.

2. Preview without uploading

galapagos submit --repo-type scaffold \
    --card-path my_scaffold/card.yaml \
    --dry-run

The preview validates the card and shows the exact bundle. A sibling config.yaml is not included implicitly, so reference it under assets (or another card field) when it belongs in the upload.

3. Upload

Mint/export a token as described in Submit to the Hub, then run:

galapagos submit --repo-type scaffold --card-path my_scaffold/card.yaml

Use --hub-url or $GALAPAGOS_HUB_URL for a self-hosted instance. The CLI sends the bundle to POST /api/scaffolds/upload; the Hub catalogs and serves it but does not execute the controller.

4. Load an implemented local scaffold

After the controller package is installed (or the card points to a supported local file spec):

import galapagos as gx

model = gx.load_model("openai/gpt-4o-mini", host="openrouter")
scaffold = gx.load_scaffold(path="my_scaffold/card.yaml", model=model)
task = gx.load_task("circle_packing")
result = scaffold.run(task=task)

Hub scaffold repository download is not wired into gx.load_scaffold("org/name"); materialize the repo first and load its local card path. Community controllers are never added to the hosted runner allowlist merely by uploading a card.