Experiment TOML

An experiment TOML file describes the image, command arguments, search space, objectives, algorithm, and run limits. Keep it alongside your workload code so changes can be reviewed and the setup reused.

The dashboard and the Go CLI, hpo, use the same shared configuration definitions. See HPO CLI to build the client from source and launch from your terminal. For a complete version 2 build configuration, see the quickstart.

Export and reuse a configuration

1. Open an existing experiment’s Settings → Export configuration and choose Export TOML.
2. Save the downloaded file in your workload repository. hpo.toml is the recommended filename; the dashboard accepts other .toml filenames too.
3. Edit the settings you want to change.
4. Open the new-experiment form in the destination project and choose Import TOML. Upload the file or paste its contents.
5. Review the imported settings, choose an experiment name, fill in required environment values, and launch.

Importing only fills the form; it does not start a run. The selected image must be accessible to the destination organization and allowed by its plan. See Publish an image.

Version 1 example

This example describes an existing image. Replace the registry, image path, and tag with an image from your organization before launching. This example assumes the executable is set in the image entrypoint. The container must accept --hpo-batch-size, --hpo-dropout, and --hpo-learning-rate, and print hpo.metrics.accuracy and hpo.metrics.latency.

hpo.toml

schemaVersion = 1
algorithm = "bayesian"
maxTrialCount = 10
parallelTrialCount = 1
maxFailedTrialCount = 3
maxRuntimeSecondsPerTrial = 60
machineSizeId = "nano"
useCustomDockerImage = false
fixedArgs = []
requiredEnv = []

[dockerImage]
registry = "registry.example.com"
image = "your-org/training"
tag = "v1"

# Each block adds one parameter.
[[parameters]]
name = "batch_size"
slug = "batch-size"
type = "categorical"
values = ["16", "32", "64"]

[[parameters]]
name = "dropout"
slug = "dropout"
type = "double"
min = 0
max = 0.5

[[parameters]]
name = "learning_rate"
slug = "learning-rate"
type = "double"
min = 0.0001
max = 0.1
log = true

# Both objectives participate independently.
[[objectives]]
name = "accuracy"
type = "maximize"

[[objectives]]
name = "latency"
type = "minimize"

Each repeated [[parameters]] block adds one parameter; each [[objectives]] adds one objective. Parameter slug determines the trial flag (learning-rate → --hpo-learning-rate). Objective name determines the reported metric (accuracy → hpo.metrics.accuracy). Objective names must be unique, with a direction on every entry. Multiple objectives have no primary metric, weighting, composite score, or overall best trial. Check algorithm compatibility before choosing a sampler.

Use the exact field names shown in exports, including camelCase. Parameters and objectives are arrays of TOML tables. Command arguments in fixedArgs retain their order. A custom commandTemplate can use parameter placeholders; see CLI parameters.

Format a configuration

hpo fmt
hpo fmt --check
hpo fmt --config path/to/config.toml

Formatting preserves comments, including inline comments and comments attached to named blocks. Parameters sort by name, then slug; objectives sort by name. Fields and sections use a fixed shared order. fixedArgs, categorical values, and condition lists retain their execution-sensitive order. Whitespace, line endings, and the final newline are normalized. No defaults are inserted, omitted optional fields stay omitted, and the schema version stays unchanged. Invalid TOML is left untouched; successful writes are atomic. --check exits with code 2 when formatting is needed.

Dashboard exports, the generated example, and CLI-created files use the same policy. Dashboard import/export preserves values rather than source comments. Export sorts a copy; it never changes the stored objective vector or how historical metrics match objective directions.

Included settings and separate inputs

Included in portable TOML	Supplied separately
Image reference and digest when recorded	Registry credentials
Fixed arguments and optional command template	Experiment name and description
Parameters, objectives, algorithm, and optional sampler settings	Destination organization (version 2 can include a target project)
Machine size and supported run limits	API keys and environment values
Optional baseline metrics	Results, trial IDs, and lifecycle controls
Required environment variable names	Current plan, quota, and funding availability

The dashboard export uses the experiment’s original trial-count and parallelism limits. It is not a snapshot of later limit changes. The API can also export current limits. For an older experiment whose original configuration was not recorded, original export may be unavailable.

Environment variables

List required names at the top level, before any TOML table:

requiredEnv = ["DATASET_TOKEN"]

The dashboard imports these names with empty values. Supply the values before launching. Never put API keys or environment secret values into the file; neither version accepts an envVars field. Do not use reserved HYPEROPTIMIZER_ names for custom environment variables.

Validation and versioning

TOML import uses the shared experiment configuration validator. Unknown schema versions and unknown root fields are rejected. Invalid settings must be fixed before import or launch; importing successfully does not guarantee that an image is accessible or that the current plan can run it.

Version 1 remains supported for portable experiment settings. Version 2 adds optional local build and destination-project settings. Change schemaVersion to 2 and add:

[target]
projectId = "01HV2T00010000000000000001"

[build]
context = "."
dockerfile = "Dockerfile"
repository = "training"
platform = "linux/amd64"

With [build], hpo optimize builds/pushes an image and supplies dockerImage before launch. To use an existing image, omit [build]. Paths are relative to the configuration file. The dashboard retains build settings as metadata but requires an existing published image to launch.

--project overrides the document target. Dashboard import uses the project selected in the dashboard. API keys and workload environment values remain separate. Unknown schema versions require a compatible CLI; files are never silently upgraded.

The generated field reference and versioned JSON Schemas come from the shared definitions. Local schema validation covers structure; online validation also applies cross-field and organization rules.

Note

Trial arguments such as --hpo-learning-rate are passed to your container. They are distinct from the hpo command installed on your computer. Your workload does not need the customer CLI to receive trial arguments or emit metrics.