XTesterONNX Models
Import ONNX, train a model from an ML profile, attach it to a strategy and run it in Launcher or on a server.
Project Catalog
Command Palette → ONNX Models. Select the intended strategy folder and start EngineHost. The catalog belongs to the active project rather than all strategies on the computer.
Import an existing ONNX or .xtmodel artifact. To train within this project, see Create and configure an ML profile. An ONNX model runs inference inside the strategy.
Inspect identifier, backend, input, outputs, features and training-data boundary. Refresh rereads the current project’s catalog. An empty list means no model is attached to this project yet.
Add ONNX or .xtmodel
Import ONNX selects an original .onnx file. The engine reads its metadata and opens Review Model Contract first. File selection alone does not commit it to the catalog.
- Open the intended project and choose the import format.
- Select a file and inspect model input and outputs.
- For ONNX, supply identifier, training boundary and any required feature vectors.
- Confirm the reviewed import and separately review any replacement.
- Check the resulting catalog entry.
For raw ONNX, provide an identifier and the actual UTC end of training data. A value such as 2025-01-01T00:00:00Z means midnight UTC; use your own training boundary instead of copying this example date.
Import .xtmodel reads a packaged contract. A sealed package cannot be edited in this form; a contract change requires a new valid package.
After review choose Import Reviewed Model. If its identifier is already attached, a separate confirmation authorizes replacement. Cancelling does not add a new catalog item.
Feature Order and Normalization
Input shape determines the number of values a strategy must prepare. Feature names preserve the training order. Rearranging values changes the input’s meaning even when its length remains correct.
Enter complete vectors with one value per feature, separated by commas or newlines. Leave names blank for host defaults. Host normalization requires both complete vectors: means and standard deviations; deviations must be positive finite numbers.
For a hypothetical three-feature input, names could be return_1, range_1, volume_1 with three corresponding values in each vector. This does not define the contract of an arbitrary downloaded model: check its actual training process.
Load additional feature names when a long list is paged. A bounded visible fragment is not a complete input contract.
Use and Check the Model
Attach the artifact first, then use its identifier through the model API available in your build. A catalog entry does not automatically produce predictions or add trading rules.
Preserve feature names, order, shape and normalization. Inputs must be available at the historical decision time. The training-data end helps check that evaluation is not using a future period already included in training.
Start with a small reproducible historical run and inspect logged inputs and outputs. An ONNX file or successful import alone does not establish predictive accuracy, absence of leakage or trading quality.
Replace or Remove
Replacing an attached identifier requires confirmation; new runs use the replacement. Retain version/fingerprint evidence for comparison rather than relying on a short model name.
Removal requires confirmation and detaches the entry from this project’s catalog. The model file remains on disk. If source still refers to its identifier, fix the binding or code before another run.
A project switch or changed source file invalidates the earlier review. Select and inspect it again in the correct project; prior confirmation is not transferred silently.
If Import Fails
Unavailable catalog: check the selected folder project and running EngineHost. Invalid UTC dates, incomplete vectors or nonpositive deviations require fixing the contract rather than repeatedly submitting it.
“Stop and close the prepared or running simulation before changing attached models.” means the engine is protecting a prepared or active strategy snapshot. Stop and close the simulation before changing model attachments. If it still refuses before a new session starts, report the version and exact reproduction to support; do not bypass validation by editing the manifest manually.
For input-shape mismatches or unsupported artifacts, use the exact engine message. Renaming another file format to .onnx does not convert it. Compare the file, feature-schema and manifest fingerprints in its entry.
Keep build version, model identifier, input/output shapes and the exact error for support. Full training data and private weights are only needed when necessary for diagnosis.
Create and configure an ML profile
Open the intended C# strategy folder, trust the workspace and wait for EngineHost to start. In the Command Palette, open ONNX Models and select ML Profiles and Training. Profiles and run history belong to that project.
- Choose Create ML Profile and enter an ID such as btc15. Use up to 64 lowercase Latin letters, digits, hyphens and underscores. Start with a letter or digit.
- In the JSON editor, check the forecast horizon, training, validation and test dates, LightGBM and MLP settings, decision threshold and costs. Save the file. Use Edit ML Profile to reopen it.
The current training template uses Binance Spot BTCUSDT one-minute candles. Save separate profiles to compare configurations on the same data.
Prepare data and train a model
Install Python 3.11, 3.12 or 3.13 for training. Studio creates a private project environment with pinned dependencies. LightGBM on macOS requires libomp. Environment setup and archive downloads need a network connection.
- Choose Prepare Python Environment, select the profile and your installed Python version, then wait for completion.
- To use the sample, choose Download BTC Sample History and wait for checksum verification. Use month boundaries for this source.
- Choose Train ML Profile. Select the downloaded sample, stored BTCUSDT Spot history or an OHLCV CSV/JSON snapshot. Wait for the job to finish. Use the progress notification or Cancel ML Training Job to stop it.
- Choose View Experiment Report and select the run. Check dates, history coverage, forecast metrics and results after the specified costs. Create a new run to evaluate another configuration.
Training snapshots the configuration and inputs. Compare LightGBM and MLP with simple baselines on the held-out period. To investigate delayed generalization, set mlp_mode=extended and define epoch and time limits. The run saves training and validation curves and checkpoints. Validation selects the checkpoint.
Attach a model version to a strategy
After training and export succeed, choose Attach Trained Model to Strategy, select the completed run and pick lightgbm or mlp. Make sure the intended strategy is active and the simulation is neither prepared nor running. Studio imports the sealed .xtmodel into the project catalog and shows its ID.
In the strategy, use Models.Open with that ID and pass the feature vector to Predict. Match the feature order and candle processing used during training. This template needs 120 consecutive closed one-minute candles. To evaluate the attached model on new history, start after the boundary of the data used for training and validation.
For a working example, choose Create ML Strategy Example and select the run and model. Open the generated folder as a separate strategy. The example logs probability_up and places no orders. Start with a small historical run and check the model version and log messages.
Run in Launcher or on a server
Save the strategy project with the attached model. Export carries the strategy and its .xtmodel together in the robot bundle. The target runs inference through the built-in ONNX runtime. The Python environment, training dataset and reports stay with the training project.
For a local run, open the strategy in Studio, choose Run in Launcher, select the local computer and choose Paper. See How a robot gets into the launcher. After startup, open the Launcher journal and check for forecasts once the candle window is ready.
For a remote run, first connect a compatible XTester server. Open the intended strategy, choose Run in Launcher and select that server. Run a Robot Here… in the server menu opens the same form. Check the strategy, server and Paper mode, confirm the launch and inspect the remote robot journal.
If you are checking the package on another machine, transfer the complete package. To use a new model version, update the model ID in the strategy, verify it again, and rebuild or update the robot.
Train and attach through MCP or Copilot
Use Connect External Agent (MCP) to bind the client to the intended project. Writes require writer access and confirm=true. In the example below, pass each JSON object to the named tool. Replace the placeholders with config_hash and job_id values from the responses. Wait for completed before proceeding to the next operation. You can use data_source=stored if Python is ready and the history is already available.
Attach takes the completed training job_id. To generate a separate example use operation=strategy, profile_id, expected_hash, training_job_id and model. To cancel, call ml_profiles_cancel with job_id and confirm=true, then read the status. If you lose the response, list jobs first. If you switched projects, reopen the original project.
In ordinary Copilot chat the tools are xtester_ml_profiles_read, xtester_ml_profiles_manage and xtester_ml_profiles_cancel. Try: “In the open project, create profile btc15, prepare Python 3.13, download the BTC sample history, train the model and show me the report. Attach LightGBM after I confirm.” Check the project shown in the confirmation. To start the robot, follow the Launcher steps above.
ml_profiles_manage {"operation":"save","profile_id":"btc15","confirm":true}
ml_profiles_read {"operation":"profile","profile_id":"btc15"}
ml_profiles_manage {"operation":"prepare","profile_id":"btc15","expected_hash":"<config_hash>","python_version":"3.13","confirm":true}
ml_profiles_read {"operation":"job","job_id":"<prepare_job_id>"}
ml_profiles_manage {"operation":"download","profile_id":"btc15","expected_hash":"<config_hash>","confirm":true}
ml_profiles_read {"operation":"job","job_id":"<download_job_id>"}
ml_profiles_manage {"operation":"train","profile_id":"btc15","expected_hash":"<config_hash>","data_source":"sample","confirm":true}
ml_profiles_read {"operation":"job","job_id":"<training_job_id>"}
ml_profiles_read {"operation":"report","job_id":"<training_job_id>"}
ml_profiles_manage {"operation":"attach","job_id":"<training_job_id>","model":"lightgbm","confirm":true}
ml_profiles_read {"operation":"models"}Run the trained strategy through an agent
Attach the model to the strategy and verify a historical run first. Agent launch actions use Paper mode.
Local Launcher. Export the robot with launcher_export_bundle or from Studio. Add the file with the launcher_add_bot action and bundlePath. Refresh the list with launcher_list_bots, then start the intended robot with launcher_start_paper_bot and its botId. Check the status and journal.
Server. Get the serverId from server_list. Call server_deploy_strategy with mode=paper and exactly one source: strategyPath for a strategy folder in the open project, or bundlePath for a portable export. If the action returns a deployId, check it under agentDeploys in server_list. Inspect the robot journal after startup.
In MCP, pass these actions to run_studio_action with action, input and confirm=true for writes. In Copilot the actions have the xtester_ prefix, for example xtester_server_deploy_strategy. For a local run, ask Copilot to add the exported file and start the intended robot in Paper after confirmation. Choose and confirm LIVE in the application window.
run_studio_action {"action":"server_deploy_strategy","input":{"serverId":"<server_id>","mode":"paper","bundlePath":"<portable_bundle_path>"},"confirm":true}
run_studio_action {"action":"server_list","input":{}}If training or launch fails
If setup or training stops, open the ML Training output and the job log. Check the Python version, dependencies, archive availability and continuity of the candle history. If the project changed, return to the folder that owns the job.
If the trained model is missing from the catalog, check the export result and select a completed run. If the strategy refuses to start, check the model ID, bundled files, input contract, market and timeframe. After a missing minute, the example builds up its candle window again. The report and forecasts alone do not establish profitability or grokking.
Related commands
Command Palette reference
Find these actions by name in the Command Palette; availability depends on the current project and operation state.
xtester.models.open