DEV Community

Cover image for How to Publish (and Pull) Your First Isaac Lab Environment on EnvHub
Mahdi Eghbali
Mahdi Eghbali

Posted on

How to Publish (and Pull) Your First Isaac Lab Environment on EnvHub

#ai #robotics #simulation #nepher

A practical guide to turning a private simulation folder into a versioned environment other teams can actually reuse.

In the first article in this series, we argued that robot learning’s hidden bottleneck is not the algorithm — it is the environment. Shared scenes, shared contracts, and shared evaluation are what make progress compound.

This piece is the smallest useful next step.

If you already have an Isaac Lab scene that works on your machine, you should be able to:

  1. package it as a proper environment bundle,
  2. publish it to EnvHub,
  3. pull it back down on a clean machine,
  4. load it in code without tribal knowledge.

That is what EnvHub is for — a category-agnostic hub for Isaac Lab / Isaac Sim environment bundles across navigation, manipulation, humanoid, locomotion, and whatever category you invent next.

No manifesto this time. Just the workflow.

What “an environment” means on Nepher

Before you touch the CLI, get the vocabulary right. Most reuse failures start here.

An environment is a bundle: one or more related simulation scenes under a shared theme, plus metadata.

Each environment has:

  • a unique id (for example digital-twin-warehouse-v1)
  • a category (navigation, manipulation, humanoid, locomotion, …)
  • a type: usd or preset
  • a version and description
  • one or more scenes

A scene is the concrete simulation configuration you actually load into Isaac Lab — a specific warehouse layout, hospital corridor, or manipulation table setup.

Two environment types matter in practice:

Type What you ship When to use it
USD .usd assets (+ optional occupancy maps) Digital twins, authored worlds, asset-heavy scenes
Preset Python files that generate the scene Procedural layouts, compact envs, code-defined variants

If your “environment” is currently a random folder with a USD and a half-written README, you do not have a reusable package yet. You have a local craft project. EnvHub’s job is to turn that craft project into something addressable.

Install the tools

You can work with EnvHub in two ways:

  • nepher — the EnvHub-focused package (list / download / upload / view / Python API)
  • npcli — the unified Nepher CLI (accounts, EnvHub, tournaments, hackathons)

For this tutorial, install both. Use npcli for auth and day-to-day EnvHub commands; use nepher when you want the Python loaders and Isaac Sim viewing helpers.

pip install nepher nepher-cli
Enter fullscreen mode Exit fullscreen mode

Confirm the CLI is alive:

npcli --version
npcli --help
Enter fullscreen mode Exit fullscreen mode

Create an API key at account.nepher.ai → Account → API Keys, then log in:

npcli login --api-key nepher_xxxxxxxx
npcli whoami
Enter fullscreen mode Exit fullscreen mode

For CI, skip interactive login and set:

export NEPHER_API_KEY=nepher_xxxxxxxx
Enter fullscreen mode Exit fullscreen mode

You are ready when whoami returns your account instead of a polite refusal.

Step 1 — Discover what already exists

Do not author a new warehouse until you check whether one already lives on the hub.

With the unified CLI:

npcli envhub list
Enter fullscreen mode Exit fullscreen mode

With the EnvHub package (category filter included):

nepher list --category navigation
nepher list --category manipulation
Enter fullscreen mode Exit fullscreen mode

You are looking for three things:

  • Does a close-enough env already exist?
  • Is the category naming consistent with how you think about the task?
  • Can you tell, from metadata alone, what the bundle contains?

If the answer to the first question is yes, skip straight to download. Reuse beats originality when the goal is comparable research.

Step 2 — Pull an environment onto a clean machine

Download by environment id:

# unified CLI
npcli envhub download <env_id>

# EnvHub package (category required)
nepher download <env_id> --category navigation
Enter fullscreen mode Exit fullscreen mode

Inspect local cache:

npcli envhub cache list
# or
nepher cache list
Enter fullscreen mode Exit fullscreen mode

If you have Isaac Sim available, open the scene visually before you wire training code:

nepher view <env_id> --category navigation
nepher view <env_id> --category navigation --scene hospital
Enter fullscreen mode Exit fullscreen mode

This is the point of a hub. A new machine, a new teammate, a new intern — same command, same world.

Step 3 — Load it in Isaac Lab code

EnvHub is not only a download manager. The nepher package gives you a small API for loading bundles into research code.

from nepher import load_env, load_scene

# Load the environment bundle
env = load_env("indoor-environments-v1", category="navigation")

# Inspect scenes
print([s.name for s in env.get_all_scenes()])
# e.g. ['hospital', 'warehouse']

# Load one scene configuration
scene_cfg = load_scene(env, scene="hospital", category="navigation")

# Hand scene_cfg into your Isaac Lab ManagerBasedRLEnv setup
Enter fullscreen mode Exit fullscreen mode

The important habit: reference environments by id + category + scene, not by absolute paths on your laptop.

Absolute paths do not travel. Bundle ids do.

Step 4 — Package your own environment

Publishing starts with a manifest.yaml. That file is the contract.

USD environment example 

id: digital-twin-warehouse-v1
type: usd
version: 1.0.0
description: Digital twin of a small warehouse environment for navigation training
category: navigation

scenes:
  - scene_id: small_warehouse
    description: Small warehouse digital twin with realistic layout and obstacles
    usd: small_warehouse_digital_twin.usd
    omap_image: digital_twin_omap/map.png
    omap_meta: digital_twin_omap/map.yaml
Enter fullscreen mode Exit fullscreen mode

Preset environment example 

id: indoor-environments-v1
type: preset
version: 1.0.0
description: Indoor navigation environments including hospital corridors and warehouse
category: navigation

preset_scenes:
  - scene_id: hospital
    description: Hospital corridor environment for indoor navigation
    preset: hospital_preset.py
  - scene_id: warehouse
    description: Warehouse with shelves and bounding walls
    preset: warehouse_preset.py
Enter fullscreen mode Exit fullscreen mode

A packaging checklist that prevents regret

Before you upload, verify:

  1. Stable id — treat the id like a package name. Do not invent a new one every Tuesday.
  2. Honest version — bump when scenes, assets, or task semantics change.
  3. Clear descriptions — write for a stranger who was not in your Slack channel.
  4. Relative paths only — everything the manifest references must live inside the bundle.
  5. Scene names that mean something — table_clutter_hard beats scene2.
  6. Thumbnail — a single image saves other people from downloading blind.

A useful folder shape looks like this:

my-env/
  manifest.yaml
  thumbnail.png
  small_warehouse_digital_twin.usd
  digital_twin_omap/
    map.png
    map.yaml
Enter fullscreen mode Exit fullscreen mode

Or, for presets:

my-env/
  manifest.yaml
  thumbnail.png
  hospital_preset.py
  warehouse_preset.py
Enter fullscreen mode Exit fullscreen mode

If a teammate cannot understand the bundle from the manifest alone, the package is not finished.

Step 5 — Upload

Upload requires contributor/evaluator access on the platform. Once you have it:

# unified CLI
npcli envhub upload ./my-env --category navigation

# EnvHub package
nepher upload ./my-env --category navigation --thumbnail ./my-env/thumbnail.png
Enter fullscreen mode Exit fullscreen mode

Then immediately test the happy path on a clean cache:

npcli envhub cache clear
npcli envhub download <your_env_id>
nepher view <your_env_id> --category navigation
Enter fullscreen mode Exit fullscreen mode

If you cannot pull and open your own environment without tribal memory, nobody else can either.

That one loop — upload → wipe cache → download → view — is the quality bar.

Common failure modes (and how to avoid them)

“It works on my machine” paths

Hardcoded absolute asset paths are the fastest way to make a bundle useless. Keep everything relative to the environment root.

Vague ids and silent overwrites

test-env-final-final2 is not infrastructure. Use readable ids and real versions.

Scene soup

One environment with twelve unrelated scenes is usually two or three environments pretending to be one. Group by theme.

Missing task semantics

EnvHub packages the world. Your Isaac Lab task code still needs a clear observation / action / reward / success contract. Publish both if you want comparable results — especially before a tournament.

Uploading before viewing

If you have not opened the scene with nepher view, you are publishing hope.

Why this is worth twenty minutes

A private Isaac Lab folder helps one person train.

A versioned EnvHub environment helps:

  • the next teammate skip a week of setup,
  • another lab compare against the same world,
  • a tournament pin a fair evaluation pack,
  • your future self remember what “warehouse-v1” actually meant.

That is how simulation stops being disposable craft and starts becoming shared infrastructure.

In article one, we said the question that matters is: Can another team reproduce our world?

EnvHub is how you answer yes.

What’s next

Next in this series: entering a Nepher tournament — how shared environments become shared scoreboards, and what it takes to submit a policy under a published brief, clock, and scoring harness.

Until then:

Pull one environment today. Package one of your own this week.

The field does not need more private warehouses. It needs addressable ones.

Nepher Robotics — simulation-first robotics development.

This is part 2 of our Simulation-First Robotics series. Part 1: “The Hidden Bottleneck in Robot Learning Isn’t Algorithms — It’s Environments.”

Top comments (0)