Code Integrity

Last updated on November 18, 2026

A Station checks before each Run that the installed Deployment is still what it installed. When a file was modified, removed or added on the station, the run is marked Modified code in the dashboard. Turn on Refuse modified code for a station and the run does not start at all.

Requires TofuPilot CLI 2.16.0 or later on the station.

How it works

The check has two steps.

StepWhenWhat the station does
SealOnce, at installVerifies the downloaded bundle against the SHA-256 the dashboard recorded for the deployment, installs it, then records a SHA-256 of every installed file.
CheckBefore each runHashes every installed file again and compares with the record.

The check runs for runs started from the kiosk, from the dashboard, and with tofupilot run --deployment.

The check reads every installed file, so its cost grows with the size of the Python environment. On a deployment of 364 MB and 10,308 files, it took about 140 ms on a development machine with the files in the system cache. Expect more on a slow disk or right after a restart.

What is checked

CheckedNot checked
The procedure file, phases and plugs.Files a phase writes beside its sources, such as a CSV, a log or a report.
Every other file the deployment shipped, such as a limits table or a configuration file.The Python interpreter, which uv installs outside the deployment.
Every Python package installed in the deployment's environment, including its compiled bytecode.Packages of the system Python, when the station is set to use them.
Files added after the install that Python, pytest, Robot Framework or TofuPilot would load: .py, .pth, .so, .pyd, .dll, .yaml, .yml, .ini, .cfg, .toml, .robot, .resource, .env files, any link, and any file added to the Python environment.The TofuPilot CLI itself.

Bytecode that Python wrote after the install is removed before each run rather than reported, so a run always compiles from the checked sources.

Two folders are exempt because their package fills them at run time: comtypes/gen and win32com/gen_py.

A procedure that rewrites a file it ships, or creates a file of the types above inside its deployment, is seen as modified from its second run. Write results to a new data file, or outside the deployment.

When a deployment was modified

What happens depends on the station's Refuse modified code setting.

SettingThe runIn the dashboard
Off (default)Starts as usual.The run is linked to its deployment and marked Modified code.
OnDoes not start. The operator sees which files differ.No run is recorded. An alert is opened if the station is online.

When a run was refused, the station screen keeps showing Modified on this station since its install for that procedure until it is installed again or the station service restarts.

Refuse modified code

Open the station's page in the dashboard and turn on Refuse modified code under Configuration. The station applies it at once when it is online, and at its next start otherwise. It keeps the setting when it is offline.

The setting needs TofuPilot CLI 2.16.0 or later on the station: the switch is disabled for a station that reports an older CLI. It is received by the station service. A machine where only tofupilot run --deployment is used, with no station service, never receives it and keeps the default.

With the setting on, a run of a modified deployment is refused before any phase starts, with up to five of the files that differ:

Deployed procedure modified on this station since its install: modified phases/power.py, added serial.py
  hint: install it again from the station screen or its page of the dashboard, or with `tofupilot pull` where no station service runs

With --json, the run ends with a run_crashed event of kind integrity_error. Its message names the files and its action is the hint.

Turn the setting on once you have seen your procedures run a few times without Modified code. A procedure that rewrites a file it ships, or creates a file of the types listed above inside its deployment, would be refused from its second run.

Install the deployment again

When a run was refused, the station screen shows Install again. The station downloads the deployment from the dashboard and installs it over the modified one. The operator then runs the procedure as usual. Try again is always on offer too, for a deployment restored from the dashboard meanwhile: the run is refused again if it was not.

You can also restore it without the operator:

  • Click Pull now on the station's page of the dashboard, while no run is in progress.
  • Push a new deployment to the station.
  • On a machine where no station service runs, run tofupilot pull.

The station's periodic checks do not restore a modified deployment by themselves.

Runs and deployments

A run is linked to a deployment when it was started from the deployment's installed folder, whether the check found it intact or modified. A run started from a source folder with tofupilot run ./my-test --upload is uploaded without a deployment, even when the same procedure is also deployed on that machine.

With each run of a deployment, the station sends a SHA-256 digest of the deployed sources it checked: the procedure's files, its locked dependencies and the deployment manifest. The dashboard compares it with the digest computed when the deployment was built, and shows the result next to the deployment on the run page.

Run pageMeaning
Verified codeThe station reported the code it checked before the run, and it is the code of this deployment's build.
Modified codeThe run did not run the code of this deployment's build: the station found its installed code modified and was not set to refuse it, or it reported another code.
nothingThere was nothing to compare: the station runs a CLI older than 2.16.0, the deployment was installed before the check existed, the deployment or one of its platform bundles was built before digests were recorded, its sources hold a link or a file name that Windows or macOS would rewrite, or the run was not uploaded with a station key.

Verified code is the station's own report, checked against the build. It is read from station keys only, and it is as trustworthy as the station: see Limits.

A run marked Modified code also opens a critical Modified code run alert, one per station and deployment, so you are told without opening each run. A run refused by a station set to Refuse modified code opens the same alert, when the station is online at that moment: a refusal on an offline station is not reported. The alert names the deployment assigned to the station. Resolving it by hand does not silence it: the next run of modified code opens it again, until the deployment is installed again.

Deployments installed before the check

A deployment installed by a CLI older than 2.16.0 has no record to compare with. It keeps running, with a warning in the station log, and is checked from its next deployment on.

Limits

The record is stored on the station. The check detects accidental and deliberate edits by anyone who cannot write as the account TofuPilot runs under. Someone who controls that account can modify the record together with the code.

To protect a station against its own operator, run TofuPilot under a dedicated account and give the operator account no write access to the TofuPilot home directory.

How is this guide?

On this page