Run and submit

Run the starter’s preview before its training job:

simulo run preview.py

The preview checks the robot inside the task, reports problems with their likely owner and recording time, and makes no policy. A passing report exits 0; a failed check exits 1 but keeps its report and recording. Fix failed checks and rerun the preview before training. See Preview before training for the full workflow.

Then submit training:

simulo run train.py

simulo run takes one Python file that holds one job. It then:

1. Imports the file to find the job. Imports inside with app.runtime.imports(): are recorded, not run, so PyTorch never loads on your computer. Because the file is imported, only run files you trust.
2. Resolves each catalog asset the app uses to an exact version.
3. Packages the app folder, leaving out what .simuloignore lists.
4. Asks Simulo whether the job would be accepted, before uploading anything.
5. Uploads the package, creates the job, and follows its logs.

The first lines it prints are the job’s type and ID, and, for a training job, the ID of the policy the job is making:

TRAIN  job_brisk-heron-4f8k2m
Policy:  policy_brisk-heron-4f8k2m

Submitting the exact same file and parameters while that job is still queued or running returns the existing job instead of starting a second one. Once it has ended, submitting the same command again starts a new job, training from scratch.

Job parameters

The job function’s parameters become flags. The starter’s train(num_envs: int = 16, max_iterations: int = 2) accepts:

simulo run train.py --num-envs 512 --max-iterations 600

A parameter you leave out keeps its default. To see the flags a file accepts:

simulo run train.py --help

Options

Flag	What it does
--detach	Submit and return without following the logs.
--tag NAME	Add a tag to the job. Repeat it to add more.
--from POLICY:KIND	Start training from a checkpoint, such as policy_brisk-heron-4f8k2m:best. See Continue training.
--policy POLICY:KIND	Play or evaluate a checkpoint, on a play or eval file. See Play a policy and record it or Evaluate a trained policy.
--compare POLICY:KIND	On an eval file with --policy, compare that checkpoint with this checkpoint on the same episodes.
--require-success RATE	On an eval file, exit 1 when the observed success rate is below RATE from 0 to 1, such as 0.9. It is refused with --detach.
--fail-if-worse	With --compare on an eval file, exit 1 when the checkpoint after --policy did worse. It is refused with --detach.
--viewstream	Stream the job’s 3D scene so simulo view can show it. Training runs roughly 4 to 5 times slower while it streams.
--frozen	Refuse to submit if any asset has no exact version (:v1, :v2, …).
--strict-assets	Refuse to submit if any asset is deprecated or hasn’t been validated on the job’s runtime.
--skip-preflight	Skip the check in step 4.

With --detach, simulo run prints the job and how to follow it, then exits:

TRAIN  job_brisk-heron-4f8k2m
Policy:  policy_brisk-heron-4f8k2m
Submitted to the cloud.
Next: simulo logs job_brisk-heron-4f8k2m --follow

Tags

simulo run train.py --tag baseline --tag cartpole

Tags let you find related jobs later with simulo jobs --tag baseline and simulo policy list --tag baseline, or with the tag filter in the Console. A job’s tags are fixed when you submit it, and its policy shows the same tags. A tag is up to 64 characters of lowercase letters, digits, ., _, and -, and a job can have up to 16.

Check before you submit

simulo prepare resolves the catalog assets from step 2 and runs the platform check from step 4, without packaging or uploading anything and without creating a job:

simulo prepare train.py

Resolved assets:
  simulo/robot/cartpole:v1  ->  v1  (sha256:abcd…)
✓ No issues found for train.py — looks ready to submit.

A finding marked ✗ would stop simulo run before it uploads anything. A finding marked ⚠ is worth knowing but doesn’t stop the submit; for example, a note that no GPU is free right now, so the job would wait in the queue. If Simulo can’t be reached for the check, both commands say so and carry on.

When you are signed in, prepare prints a Resolved assets: block that names the exact version selected for each catalog reference. A missing asset or version exits nonzero with the same message as simulo run. When you are signed out, the catalog endpoint is absent, the platform returns a server error, or the network is unavailable during session refresh or asset lookup, it prints Asset references were not checked. and does not fail for that reason. A rejected session still asks you to sign in, and an unknown asset or version still exits nonzero. Local file discovery still runs.

Submit each job type

Every job declares a type, such as @app.job(type="train"). Train, play, preview, and eval jobs can all be submitted. simulo run play.py --policy policy_x:best runs a checkpoint back instead of training one, simulo run preview.py checks your robot and task before you train and makes no policy, and simulo run eval.py --policy policy_x:best measures a trained checkpoint. Use --compare policy_y:best with an eval command to judge a candidate checkpoint against a baseline on the same episodes. Add --fail-if-worse when a script must stop on a detected regression, and --require-success 0.9 when it must also stop below a 90% observed success rate. See Evaluate a trained policy for the report, recordings, and pipeline use.

When you’re not signed in

If you haven’t run simulo login, simulo run writes the package locally, under .simulo/packages/ in the app folder, and does not run it:

This wrote a local package only. Log in to submit to the Simulo cloud instead:
    simulo login

Next

Observe the training job and the policy it makes.