Asset catalogs & version pinning

An asset is a versioned USD or URDF package that a job reads as an input: a robot, a world, or a prop. You publish a package once and get a catalog reference for it. Every job that uses the reference is pinned to one exact, unchangeable version when you submit it.

Two catalogs, one reference format

Every reference has this shape:

[publisher/]kind/name[:vN]

Reference	Meaning
robot/my-arm:v1	Version 1 of my-arm in your organization’s catalog.
robot/my-arm	The latest published version of my-arm in your organization’s catalog, resolved when you submit.
simulo/robot/cartpole:v1	Version 1 of cartpole in the read-only Simulo catalog.

The three kinds are robot, world, and prop.

• The Simulo catalog holds ready-to-use, validated, read-only assets. Their references start with simulo/.
• Your organization’s catalog holds the assets your team publishes. Their references have no publisher, and your team decides when to deprecate or delete them.

The two catalogs never stand in for each other: robot/cartpole does not mean simulo/robot/cartpole.

simulo asset list              # your organization's catalog
simulo asset list --global     # the Simulo catalog
simulo asset search warehouse  # both, labeled by catalog

Publish once, reuse by name

1. Package it on your machine. simulo asset publish finds the USD or URDF entry file and every file it depends on, and refuses a dependency that lives outside the package folder.

2. Upload it. Large packages upload in parts and can resume after an interruption.

3. Validate it in the cloud. An asset_validation job checks the package. A URDF robot is converted to USD, and every robot is settled and actuated in the simulator. See Asset validation.

4. Publish a version. The next vN is assigned only after validation passes. A version never changes afterwards; publishing different content creates a new version.

simulo asset publish ./my-arm --kind robot --name my-arm
simulo asset inspect robot/my-arm:v1

Bring your own robot walks through the whole flow.

Pinning happens when you submit

Create an asset handle at module level, where simulo run sees it while it imports your file:

import simulo

my_arm = simulo.Asset.from_registry("robot/my-arm:v1")


class PickTask(simulo.Task):
    def build(self, scene: simulo.Scene) -> None:
        self.robot = simulo.Robot(asset=my_arm, initial_pose=simulo.Pose.identity())
        scene.add(self.robot, at="/World/Robot")

Before the job is created, Simulo resolves every handle to an exact version and records that pin on the job permanently. The GPU machine downloads that exact package and checks its digest before the job starts. A handle created inside build() is never seen at submit, so the job fails before training with an error saying the asset is not mounted. Move the handle to module level.

A reference without :vN is convenient while you explore:

my_arm = simulo.Asset.from_registry("robot/my-arm")

That job is still pinned to one exact version, but the next submit may pick up a newer one. Two flags tighten this for pipelines:

simulo run train.py --frozen                   # refuse any reference without :vN
simulo run train.py --frozen --strict-assets   # also refuse deprecated or unvalidated versions

Without --strict-assets, a deprecated version, or one never validated on the job’s runtime, is accepted with a warning.

Deprecating and deleting

A published version can be deprecated and later reactivated. Deprecating hides it from list and search and makes new submits warn; jobs that already pinned it are unaffected.

Deleting is guarded by job history. simulo asset delete is refused while any job references the version. --force deletes it anyway, for your own organization’s assets only: the files are removed for good and the jobs that used it show the reference as deleted. Assets in the Simulo catalog can’t be deleted, and simulo asset get downloads only your own organization’s assets.

Browse and manage assets has the exact commands.