Skip to contentYour program receives the selected values.
--hpo-stop-loss-pct 3
--hpo-take-profit-pct 12Parse these arguments in your language of choice. Fixed arguments are shared across trials; sampled parameter values can change.
Inside the product
An experiment.
Every setting, explained.
Your code is the workload. Your experiment defines what can change, what to measure and how far to search.
The experiment file
Read the settings. See what they do.
Explore one complete configuration for a trading workload with two parameters. Select a part of the file to understand its role.
[[parameters]]
name = "stop_loss_pct"
slug = "stop-loss-pct"
type = "int"
min = 1
max = 10
[[parameters]]
name = "take_profit_pct"
slug = "take-profit-pct"
type = "int"
min = 2
max = 25The values your search can change.
A parameter describes a set of allowed values. A trial receives one concrete value from that set.
name- The parameter’s name in the experiment and its results.
slug- The command-line flag: stop-loss-pct becomes --hpo-stop-loss-pct.
type- Use int for whole numbers, double for decimals, or categorical for a list of choices.
min / max- The bounds the search is allowed to explore. Here, stop loss ranges from 1 to 10.
The same workload and evaluation data should be used across trials so the comparison is meaningful.
Read the field reference ↗[[objectives]]
name = "final_portfolio_value"
type = "maximize"The measurement that defines better.
Tell the search which reported metric to optimize and which direction is better.
name- Must match the metric printed by your program: hpo.metrics.final_portfolio_value.
type- maximize prefers larger values. minimize prefers smaller values, such as loss or latency.
[[objectives]]- Each block adds an objective. Multiple objectives retain their own directions; they are not merged into one score.
You can report additional metrics for inspection without making all of them optimization objectives.
Read the field reference ↗schemaVersion = 2
algorithm = "bayesian"
maxTrialCount = 120
parallelTrialCount = 10
maxFailedTrialCount = 3
maxRuntimeSecondsPerTrial = 300
machineSizeId = "small"Choose the search and its boundaries.
These settings describe how the experiment runs. They do not change what your program measures.
algorithm- bayesian uses completed results to guide subsequent parameter suggestions. Explore the methods below.
maxTrialCount / parallelTrialCount- 120 trials in total, with up to 10 running at once, subject to available workspace capacity.
maxRuntimeSecondsPerTrial- 300 seconds is the timeout for each trial, not the duration of the entire experiment.
maxFailedTrialCount- A failure limit of 3 bounds how many failed trials the experiment tolerates.
machineSizeId- The compute size for each trial. Availability and compute consumption depend on the machine and plan.
schemaVersion = 2 enables local build settings. Compute eligibility and plan limits still apply.
Read the field reference ↗[build]
context = "."
dockerfile = "Dockerfile"
repository = "trading-strategy"
platform = "linux/amd64"Point to the code every trial runs.
This example asks the CLI to build and push your local Docker image before launching cloud trials.
context / dockerfile- Find the build context and Dockerfile relative to hpo.toml.
repository / platform- Name the image repository and its target platform.
[dockerImage]- Already published an image? Omit [build] and supply registry, image and tag in a [dockerImage] table instead.
Dashboard launch requires an existing published image. Imported build settings are retained as metadata.
Read the field reference ↗useCustomDockerImage = false
fixedArgs = []
requiredEnv = []Keep shared settings separate from secrets.
Some inputs stay fixed across all trials. Credentials and environment values are supplied separately.
fixedArgs- Arguments shared by every trial. Their order is preserved. An empty list adds none.
requiredEnv- Names of environment variables your workload needs. This example needs none; values do not belong in the file.
useCustomDockerImage- false uses your organization’s registry. External images require a plan that allows them and this flag set to true.
Project & credentials- Choose the destination project in the dashboard or CLI. API keys and registry credentials remain separate.
TOML import fills the form; it does not launch an experiment or grant access to an image.
Read the field reference ↗View the complete hpo.toml
schemaVersion = 2
algorithm = "bayesian"
maxTrialCount = 120
parallelTrialCount = 10
maxFailedTrialCount = 3
maxRuntimeSecondsPerTrial = 300
machineSizeId = "small"
useCustomDockerImage = false
fixedArgs = []
requiredEnv = []
[build]
context = "."
dockerfile = "Dockerfile"
repository = "trading-strategy"
platform = "linux/amd64"
[[parameters]]
name = "stop_loss_pct"
slug = "stop-loss-pct"
type = "int"
min = 1
max = 10
[[parameters]]
name = "take_profit_pct"
slug = "take-profit-pct"
type = "int"
min = 2
max = 25
[[objectives]]
name = "final_portfolio_value"
type = "maximize"An adaptable example, not a bundled strategy. Provide your own Dockerfile, workload and data. The CLI and dashboard use the same configuration definitions.
The execution contract
From a setting to a running container.
The file describes the search. Each trial runs your program once, with actual parameter values. Here is how a value reaches your code and a measurement comes back.
Your program reports the measurement.
hpo.metrics.final_portfolio_value=12840Print a numeric metric using the configured objective name. HyperOptimizer collects it with the trial’s parameters, status and logs.
Values above are illustrative. Your workload performs the evaluation; HyperOptimizer does not supply a strategy or invent the score.
Container requirements ↗Execution boundaries
Three limits. Three different jobs.
Trial count, parallelism and timeout answer different questions. None is a promise about total wall-clock duration or a fixed bill.
How many configurations?
maxTrialCountThe total trial limit for this experiment. The search can stop earlier when other limits or configured goals are reached.
How much parallel work?
parallelTrialCountThe requested concurrency. Available workspace slots and compute eligibility can reduce how many trials run together.
How long may one run take?
maxRuntimeSecondsPerTrialThe timeout for an individual trial. It does not mean the whole experiment finishes in five minutes.
You can intervene.
Follow progress and inspect failures from the experiment dashboard.
- Pause
- Stop new suggestions; in-flight trials may finish.
- Resume
- Continue suggestions when compute eligibility and limits allow.
- Stop
- Stop new work and let the experiment drain toward a stopped state.
- Failure limit
maxFailedTrialCount = 3bounds tolerated failures in this example. Inspect logs to diagnose the cause.
Compute use depends on trial runtime and machine size. Plan limits, billing eligibility and renewal interruptions still apply. See pricing and compute terms ↗
One setting, several strategies
How the next configuration is chosen.
The algorithm selects candidate values within your search space. It works inside the experiment’s execution and metric contract. Explore three methods below.
Parameter distributionsMethod illustration
Bayesian optimization
Bayesian / TPE
Learn where to look next.
Use completed trials to model promising parameter values, then propose candidates informed by what you have observed.
- Observe
- Separate stronger results from the remaining observations.
- Model
- Estimate the parameter distributions of both groups.
- Propose
- Compare those distributions to choose new candidates.
Sampling distributionMethod illustration
Evolutionary search
CMA-ES
Adapt where you sample.
Use evaluated candidates to update the center, scale and orientation of a sampling distribution for numerical parameters.
- Center
- Move the distribution using evaluated candidates.
- Scale
- Expand or contract the search as needed.
- Orientation
- Adapt to relationships between parameters.
Parameter spaceMethod illustration
Space-filling exploration
Sobol
Cover the possibilities.
Explore a numerical parameter space with a low-discrepancy sequence. Samples spread systematically without learning from objective values.
- Coverage
- Distribute samples across the parameter space.
- Sequence
- Add points in a structured, repeatable order.
- Exploration
- Choose locations independently of trial results.
Propose the next candidate
Reading the evidence
Know what a result does—and doesn’t—tell you.
A high score answers the question you configured, on the data your workload evaluated. Choosing that question carefully matters as much as searching it.
A direction makes the ranking meaningful.
Maximize final portfolio value, or minimize loss. Compare the reported metric alongside the parameter values and logs that produced it.
Look beyond the winning number.
Your program can report additional metrics. For example, inspect drawdown alongside return without making both optimization objectives.
Different goals retain their own directions.
Add an [[objectives]] block for each goal. They are not combined into a weighted score, and there is no single overall best trial. Pareto views are future work.
A promising configuration still needs validation.
Keep evaluation data consistent during search. Then test promising settings on held-out data in your own workload; a strong search result does not establish future performance.
Keep the definition with your code
Reuse the setup. Keep its history clear.
Version hpo.toml alongside your workload. Review changes to the search space, objectives and limits before running another experiment.
From your terminal
hpo fmt
hpo validate
hpo optimizeAfter authenticating and selecting your project, format and validate the file. With [build], the CLI builds and pushes your image before launching.
From the dashboard
Export TOML from an experiment’s settings. Import it into a new experiment, review the settings, select an accessible image and supply required environment values before launching.
Import fills the form. It does not start a run. Dashboard export uses the original trial-count and parallelism limits, rather than later limit changes.
Import and export details ↗Travels in the file
Image or build settings, arguments, parameters, objectives, algorithm, run limits and required environment names.
Supplied separately
Credentials and secret values. Experiment names and results. Choose a destination project, or set an optional v2 [target].
Connect your workload
The same contract, with your tools.
Docker
Any language, your libraries and dependencies.
Freqtrade
Connect a parameterized strategy backtest.
NautilusTrader
Run your Nautilus strategy in trial containers.
HPO CLI
Build, validate and launch from your terminal.
Make your first experiment
a question you can answer.
Start with a small search space and a metric you trust. Confirm one trial works, then expand the search.
7-day Starter trial · payment details required. Need a hand? Talk to us.