Asset Catalogs & Version Pinning

An asset is a versioned USD or URDF package that a job can consume as a read-only input. Publishing a model once gives it a stable catalog reference; submitting a job resolves that reference to an immutable version and records the exact content with the job.

Two catalogs, one reference grammar

Every reference has this shape:

[publisher/]kind/name[:vN]

Reference	Meaning
robot/my-arm:v1	Version 1 of my-arm in your active organization’s catalog.
robot/my-arm	Your organization’s latest published my-arm version, resolved at submit.
simulo/robot/cartpole:v1	Version 1 of cartpole in the read-only Simulo global catalog.
simulo/world/warehouse:v1	A global world package.

The three kinds are robot, world, and prop. The publisher is explicit for the global catalog and omitted for your own organization. Catalogs never fall back to each other silently: robot/cartpole does not mean simulo/robot/cartpole.

From an end-user perspective, the difference is simple:

• Simulo global catalog — ready-to-use, validated, read-only assets. Refs begin with simulo/; browse them with simulo asset list --global.
• Your organization’s catalog — assets your team validates and publishes. Refs omit the publisher and your team controls their lifecycle.

Browse the two scopes independently, or search both at once:

simulo asset list
simulo asset list --global
simulo asset search warehouse

Publish once, reuse by name

1. Inspect and package locally. The client finds the USD/URDF entry and its in-package dependencies, computes a manifest and digest, and refuses paths that escape the package root.

2. Upload. Small packages use a single upload; large packages use a resumable multipart upload.

3. Validate in the cloud. Structural and USD-schema checks run first. URDF robots are converted to USD. Robot packages also run physics completion plus settle and actuation probes.

4. Publish an immutable version. A monotonic vN is assigned only after validation passes. Publishing changed content creates a new version; it never mutates an old one in place.

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

See Bring your own robot for the end-to-end authoring flow and Asset Validation for how to read the report.

Submit-time resolution is the reproducibility boundary

Use a catalog asset as a module-level handle:

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")

simulo run captures handles constructed while it imports your app. Before a cloud job is created, the control plane resolves each reference to a canonical version and the job stores that pin permanently. The claim sent to execution contains the canonical reference and digest; the downloaded package is digest-verified before use.

An unversioned ref is convenient during exploration:

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

It still becomes an exact pin for that job, but a later submit may resolve to a newer version. Use --frozen when a pipeline must reject that ambiguity:

simulo run app.py --frozen

Use --strict-assets to promote asset warnings to submit errors. It rejects a deprecated version or one that has never been validated on the job’s runtime, instead of accepting the submit with a warning.

simulo run app.py --frozen --strict-assets

Lifecycle and deletion safety

Published versions can be deprecated and later reactivated. Deprecation hides the version from normal discovery and warns new submits; it does not alter jobs that already pinned it.

Deletion is guarded by job history. A normal delete is refused while any job references the version. --force is available only for your own catalog and permanently removes the bytes while leaving a tombstone on affected job records. Global catalog versions cannot be force-deleted or downloaded with simulo asset get.

See Browse & manage assets for the exact commands and safeguards.