#Runtime instances

Create independently managed local laboratory instances from immutable asset packages. The released lab executable includes instance management and the local asset daemon. The first runtime is built-in kinematic; Docker, a Hub account, and laboratory hardware are unnecessary.

#Prepare a runnable package

From the OpenSDL checkout root, use examples/kinematic-lab. It contains an asset manifest, OpenUSD scene, GLB preview, and world configuration. Choose an output directory that does not exist:

lab validate examples/kinematic-lab
export LAB_ASSET_CACHE="$PWD/lab-store"
lab daemon start
lab build examples/kinematic-lab --tag localhost/lab/kinematic:1.0.0 --cache-dir ./lab-store

#Create and start

run creates and starts an instance, returning only after authentication and device readiness. create prepares a stopped instance. Names begin with a lowercase letter and contain lowercase letters, digits, hyphens, or underscores, up to 63 characters.

lab instance run localhost/lab/kinematic:1.0.0 --name demo --cache-dir ./lab-store
lab instance list --cache-dir ./lab-store
lab instance inspect demo --json --cache-dir ./lab-store

The complete lifecycle can also use Docker-style top-level shortcuts:

lab run localhost/lab/kinematic:1.0.0 --name demo
lab ps --json
lab logs demo --tail 20
lab stop demo
lab start demo
lab stop demo
lab rm demo

lab stop NAME stops a managed instance; lab stop without a name keeps its existing meaning of shutting down a standalone lab serve process. See Hub Quick Start for the copyable discovery, digest pull, offline reuse, and cleanup workflow.

An instance freezes its creation-time digest and world configuration. Later tag changes cannot retarget it. Each instance has separate runtime data, logs, authentication, and port allocation; gRPC listens only on local loopback.

#Inspect devices and call actions

lab instance devices demo --json --cache-dir ./lab-store
lab instance send demo sim:example-lab:heater-1 start --cache-dir ./lab-store
lab instance logs demo --tail 10 --cache-dir ./lab-store

The example world exposes a heater, stirrer, valve, and sensor. An action result of PENDING means dispatched; inspect device state for its effect. Kinematic provides deterministic built-in state evolution, rather than rigid-body or robot dynamics. Public Hub packages declaring only visual can be downloaded and inspected, but require an explicit runtime declaration before instance creation.

#Stop, restart, and remove

lab instance stop demo --cache-dir ./lab-store
lab instance list --all --json --cache-dir ./lab-store
lab instance start demo --cache-dir ./lab-store
lab instance stop demo --cache-dir ./lab-store
lab instance remove demo --cache-dir ./lab-store

Stopping retains logs, data, and package occupation. Restart uses the frozen initial world configuration; it does not restore previous live telemetry. A running instance cannot be removed: stop it first. Removal releases package occupation only after the instance has been removed. The instance is unavailable remotely when its device is offline.

#Reclaim assets

lab asset remove localhost/lab/kinematic:1.0.0 --cache-dir ./lab-store
lab asset prune --dry-run --json --cache-dir ./lab-store

After checking the dry-run result, use lab asset prune --json --cache-dir ./lab-store to reclaim unreferenced, unoccupied packages. GC deletes only blobs owned by this store and preserves shared content needed by retained packages.

#Runtime declaration

A runnable asset declares its configuration entry under spec in asset.yaml and includes the simulation capability:

spec:
  # Other asset fields remain required.
  capabilities: [visual, scene, simulation]
  runtime:
    engine: kinematic
    config: world.yaml

world.yaml is a bundled SimulationConfig, for example:

world_id: example-lab
engine: kinematic
tick_hz: 10
seed: 0

Omitting devices uses the built-in four-device world. Configuration describes simulation only; unknown fields are rejected. It cannot declare device transports, external programs, or credentials. The configuration must be a relative YAML path inside the package and is read and validated at instance creation. General hardware configuration is not accepted.

#Failures and diagnostics

Failed records remain in list --all and can be examined with inspect and logs. A crashed process is detected as failed; a valid prepared instance can restart. Failed configuration preparation requires removal and recreation. If process identity cannot be verified, stop reports an error instead of killing a process solely by its recorded PID.

Interrupted deletion retains a removing record and package occupation. Repeat lab instance remove to continue; this state cannot start. An interrupted creation is marked failed on inspection and remains explicitly removable.