Quickstart

This guide wires a Dockerized workload to HyperOptimizer. By the end, your container can receive HPO parameters, run one trial, print metrics, and run as an experiment from an image in your org registry.

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.

1. Image: Your Docker image contains your code and dependencies.
2. Arguments: HyperOptimizer appends --hpo-* flags for each trial (or plain --* if you choose that mode).
3. Output: Your program prints hpo.metrics.<key>=<json>.
4. Publish: You push the image to Dashboard → Images.
5. Experiment: You create an experiment in the dashboard that picks that image and defines the search space.

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 output

hpo.metrics.sharpe=1.85
hpo.metrics.max_drawdown=0.12
hpo.metrics.profit_factor=1.29

4. Publish to Images

Free, Starter, and Pro trials must run images from your org Images registry.

1. Open Dashboard → Images and copy the login command.
2. Tag and push:

docker tag your-local-image:latest <registry-host>/<project>/my-app:v1
docker push <registry-host>/<project>/my-app:v1

3. Refresh Images until the tag appears.

Full steps (including GitHub Actions): Publish an image.

5. Create the experiment

In the dashboard, open Experiments → New. The wizard walks through:

Step	What you set
Image	Repository and tag from Images
Command	Image CMD plus managed parameters (--hpo-* by default; optional plain --* or {{slug}} templates)
Parameters	Search space: whole numbers, continuous values, fixed choices, true/false
Objectives	One or more metrics to maximize or minimize (names must match stdout keys)
Run settings	Parallelism, max trials, max failed trials, max runtime, machine size, optional spend limit
Environment	Optional custom env vars (names starting with HYPEROPTIMIZER_ are reserved)
Algorithm	Default: Bayesian (TPE)

Start narrow and with low parallelism until the first trials succeed. Details: Create an experiment.

Ready checklist

• Your image can run one trial from its default command.
• Your code accepts every configured --hpo-* argument (or plain flags if you chose that mode).
• Your trial exits with code 0 when metrics are valid.
• Your program prints at least one hpo.metrics.* line.
• The objective metric names match the dashboard configuration.
• The image is published under your org Images project and selected in the wizard.