Quickstart

This guide wires a Dockerized workload to HyperOptimizer. By the end, your container can receive HPO parameters, run one trial, and print metrics in the format our collector reads.

What you will build

HyperOptimizer treats your program as a repeatable trial runner. The platform starts the container with one parameter set, waits for it to finish, and reads matching metric lines from stdout.

Image

Your Docker image contains your code and dependencies.

Arguments

HyperOptimizer appends --hpo-* flags for each trial.

Output

Your program prints hpo.metrics.<key>=<json>.

Dashboard

The dashboard ranks completed trials by the objective metric.

1. Build your image

Use any base image. The only requirement is that the default command runs one trial and exits.

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

# HyperOptimizer appends --hpo-* args to this command.
CMD ["python", "main.py"]

2. Parse HPO parameters

We inject parameters as standard CLI arguments. Choose names that map cleanly to your model, simulation, or backtest.

import argparse

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--hpo-lookback-window", type=int, default=20)
    parser.add_argument("--hpo-risk-multiplier", type=float, default=1.0)
    return parser.parse_args()

args = parse_args()

result = run_trial(
    lookback_window=args.hpo_lookback_window,
    risk_multiplier=args.hpo_risk_multiplier,
)

3. Emit metrics

Print one metric per line. Values must be JSON-serializable.

import json

metrics = {
    "sharpe": result.sharpe,
    "max_drawdown": result.max_drawdown,
    "profit_factor": result.profit_factor,
}

for key, value in metrics.items():
    print(f"hpo.metrics.{key}={json.dumps(value, default=str)}")

Collector-visible outputcollected

hpo.metrics.sharpe=1.85

hpo.metrics.max_drawdown=0.12

hpo.metrics.profit_factor=1.29

4. Create the experiment

In the dashboard, create an experiment that points at your image and defines the search space.

Name
image
Type
string
Description
Container image to run for each trial.
Name
parameters
Type
range | choice
Description
Names and bounds for the values HyperOptimizer should try.
Name
objective
Type
metric key
Description
Metric to maximize or minimize, such as sharpe or loss.
Name
parallelism
Type
integer
Description
Number of trial containers to run at the same time.

Ready checklist

Your image can run one trial from its default command.
Your code accepts every configured --hpo-* argument.
Your trial exits with code 0 when metrics are valid.
Your program prints at least one hpo.metrics.* line.
The objective metric name matches the dashboard configuration.

Next, read the metric format reference or jump into the Freqtrade integration.