openremap tune

Apply a tuning recipe to a target ECU binary in a single command.

openremap tune runs three phases automatically:

The original file is never modified. The tuned binary is written only when all three phases pass. Exit code 0 = success, 1 = any phase failed.

New here? Read the plain-English introduction first.

🔴 CHECKSUM VERIFICATION IS MANDATORY

openremap tune does NOT calculate or correct ECU checksums. Before flashing any tuned binary to a vehicle you must run it through a dedicated checksum-correction tool — ECM Titanium, WinOLS, Checksum Fix Pro, or equivalent. Phase 3 confirms the recipe was applied correctly; it does not replace a checksum tool. Flashing a binary with an incorrect checksum will brick your ECU.

Usage

openremap tune <TARGET> <RECIPE> [OPTIONS]

Arguments

Options

Same-file-only recipes (--force)

A recipe cooked with cook --allow-non-unique carries the stamp metadata.portability = "same_file_only" — its anchors are not unique, so it is only safe on the exact binary it was cooked from. tune enforces this: the target's sha256 must equal the recipe's ecu.sha256, otherwise tune refuses (exit 1):

❌  recipe is stamped SAME-FILE-ONLY (non-unique anchors) and the target's
    sha256 (…) does not match the source (…). It may only be applied to the
    exact binary it was cooked from — pass --force to override.

--force overrides only this policy gate, with a loud warning. The mechanical checks are untouched and can still abort: Phase 1 (every ob at its exact offset), Phase 2 (anchor search), Phase 3 (post-patch write verification). A truly different revision fails Phase 1 even with --force; a close variant whose anchors still hold applies and verifies. openremap validate before reports the same mismatch so you can check before forcing.

Examples

# Apply a tune — all three phases run automatically
openremap tune target.bin recipe.remap

# Specify where to write the tuned binary
openremap tune target.bin recipe.remap --output my_tuned.bin

# Save the combined three-phase report as JSON
openremap tune target.bin recipe.remap --report tune_report.json

# Save both the tuned binary and the report
openremap tune target.bin recipe.remap --output my_tuned.bin --report my_report.json

# Skip Phases 1 and 3 (scripted pipelines only)
openremap tune target.bin recipe.remap --skip-validation

# Print the full three-phase report as JSON to the screen
openremap tune target.bin recipe.remap --json

Example output

All three phases passed

  openremap tune  target.bin  +  recipe.remap

  ──────────────────────────────────────────────────────────
  Phase 1 — Pre-flight check  (validate before)

  Target                   target.bin
  MD5                      abc2e7d4610bfda5619951e015566e8d
  Instructions             277
  Passed                   277

  ✅ Target matches recipe — safe to apply

  ──────────────────────────────────────────────────────────
  Phase 2 — Applying tune

  Instructions             277
  Applied                  275
  Shifted                    2
     Shifted instructions were recovered via ±2 KB anchor search.

  ✅ Recipe applied — 275/277 instructions written

  ──────────────────────────────────────────────────────────
  Phase 3 — Post-tune verification  (validate after)

  Instructions             277
  Confirmed                277

  ✅ All mb bytes confirmed in tuned binary

  ──────────────────────────────────────────────────────────
  ✅ Tune complete

  Target MD5               abc2e7d4610bfda5619951e015566e8d
  Tuned MD5                f3c1a9b2d8e7041256ff34c2ab987d31
  Tuned binary             target_tuned.bin

  ⚠  MANDATORY: correct checksums with ECM Titanium, WinOLS, or
     a similar tool before flashing the tuned binary to a vehicle.
     Flashing without checksum correction will brick the ECU.
  ──────────────────────────────────────────────────────────

Phase 1 failed — nothing written

  openremap tune  target.bin  +  recipe.remap

  ──────────────────────────────────────────────────────────
  Phase 1 — Pre-flight check  (validate before)

  ⚠  Match key mismatch:
     recipe : EDC17C66::1037541778
     target : EDC17C66::1037541779

  Target                   target.bin
  MD5                      ff3a91b2...
  Instructions             277
  Passed                   261
  Failed                    16

  Failed instructions:
     #  12  offset 0x0012A4F0  — ob not found at offset
     #  13  offset 0x0012A510  — ob not found at offset
     …

  Tip: run  openremap validate check  to find out why.

  ❌ NOT safe to apply — 16 instruction(s) failed.
     Run  openremap validate check  to diagnose.

Phase 2 and Phase 3 do not run; the tuned binary is not written.

What to look for

Running phases individually

tune is the recommended path for interactive use. To inspect a phase in isolation — a report, a script, or diagnosing a failure — the individual validate sub-commands run the same underlying logic:

# Phase 1 only — pre-flight check
openremap validate before target.bin recipe.remap

# Diagnostic — why did Phase 1 fail?
openremap validate check target.bin recipe.remap

# Phase 3 only — post-tune confirmation
openremap validate after target_tuned.bin recipe.remap --json --output verify.json

Notes

• The original TARGET file is never modified; the tuned result is always a separate output file.
• An existing output path is overwritten. Use --output to pick a specific path if you want to preserve a previous version.
• --skip-validation bypasses Phases 1 and 3 — only for scripted pipelines that already validated separately.
• The --report JSON contains all three phases under the keys phase_1_validate_before, phase_2_apply, and phase_3_validate_after, plus a top-level success boolean — useful for CI, auditing, and sharing results. With --skip-validation, the skipped phase objects carry "skipped": true.
• Exit codes: 0 on success, 1 if any phase fails.

See also

• tune — API — the same three-phase apply from Python or JSON-RPC
• validate — the individual steps
• cook — build the recipe you apply
• audit — the receipt check afterwards