Three small but reproducible documentation/UX gaps observed during a first-time cold-start deploy session. All observed within the first 30 minutes of the launchable being live, before writing any custom code. Each has a clear, low-cost fix.
For context: came in with zero prior Isaac Sim experience, deployed cleanly, completed both create_empty.py (streaming hello-world) and the Ant RL training/play demo successfully. The launchable works. These are the small first-impression frictions on the path to that success.
1. README path /workspace/isaaclab doesn't match the filesystem layout (web VS Code vs SSH)
The in-instance README's first command is cd /workspace/isaaclab && ./isaaclab.sh -p .... This works in the web VS Code terminal. But:
- Web VS Code file tree: shows
/workspace/isaaclab/ (no hyphen)
- SSH via
brev shell <instance>: shows ~/isaac-launchable/isaac-lab/ (with hyphen) at the host level
- The host-level
~/isaac-launchable/isaac-lab/ directory contains docker-compose infrastructure files, NOT the Isaac Lab framework code. The framework lives inside a container.
A user who reads the README and types the command verbatim in web VS Code: works. A user who SSHes in and tries the same command: hits no such file or directory (web path doesn't exist on the host), or navigates to the closest-named directory and finds infrastructure files instead of framework code.
Proposed fix
Pick one canonical directory name and use it consistently across README, web VS Code workspace mount, and host filesystem. OR add a "Two ways to access" section to the README noting the web VS Code is the recommended entry point and SSH requires docker exec -it <container> bash to reach the framework environment.
2. In-instance README and GitHub README disagree on what the hello-world IS
Pre-deploy research fetched the GitHub README, which positions the Ant RL training task as the canonical first-run example. The README rendered inside the deployed instance positions create_empty.py as the first-run example instead. Both demos work; both make sense as introductions. But a new user has no way to know which "first step" to follow, especially if they read the GitHub version before deploying and then the in-instance version after.
Proposed fix
Pick one canonical first-run example and use it consistently across both READMEs. Or cross-link with a note: "if you're reading this in the deployed instance, run create_empty.py first to verify streaming; if reading on GitHub before deploying, here's the high-level overview of both demos."
3. Web VS Code (code-server) opens a generic Microsoft walkthrough as the first tab, not the launchable's README
When the deploy completes and the user opens the web VS Code URL, the first tab is the generic "Get Started with VS Code for the Web" walkthrough (theme picker, command palette intro). The launchable's README.md, which contains the actual first-run instructions, is not surfaced until the user manually closes the walkthrough and opens it from the file tree.
For a paid first-time launchable, the first-impression tab being "unrelated VS Code tutorial" rather than "here's what to do in this Isaac Sim environment" is a wrong default.
Proposed fix
In the launchable's startup script (or code-server config), dismiss the generic walkthrough by default and open README.md in preview mode as the initial tab. Both are code-server settings changes.
Notes
- The
[N] app ready log line being buried in ~200 lines of startup noise is upstream Isaac Sim behavior and harder to address from the launchable side, so noting separately rather than including here.
- Other friction I hit later writing a custom standalone script (
ISAAC_NUCLEUS_DIR = None with bare SimulationApp, prim_path needing an Xform parent) traces back to my own deviations from the canonical IsaacLab pattern, so not filing those here either.
Happy to break any of the above into separate issues if that's preferred.
Three small but reproducible documentation/UX gaps observed during a first-time cold-start deploy session. All observed within the first 30 minutes of the launchable being live, before writing any custom code. Each has a clear, low-cost fix.
For context: came in with zero prior Isaac Sim experience, deployed cleanly, completed both
create_empty.py(streaming hello-world) and the Ant RL training/play demo successfully. The launchable works. These are the small first-impression frictions on the path to that success.1. README path
/workspace/isaaclabdoesn't match the filesystem layout (web VS Code vs SSH)The in-instance README's first command is
cd /workspace/isaaclab && ./isaaclab.sh -p .... This works in the web VS Code terminal. But:/workspace/isaaclab/(no hyphen)brev shell <instance>: shows~/isaac-launchable/isaac-lab/(with hyphen) at the host level~/isaac-launchable/isaac-lab/directory contains docker-compose infrastructure files, NOT the Isaac Lab framework code. The framework lives inside a container.A user who reads the README and types the command verbatim in web VS Code: works. A user who SSHes in and tries the same command: hits
no such file or directory(web path doesn't exist on the host), or navigates to the closest-named directory and finds infrastructure files instead of framework code.Proposed fix
Pick one canonical directory name and use it consistently across README, web VS Code workspace mount, and host filesystem. OR add a "Two ways to access" section to the README noting the web VS Code is the recommended entry point and SSH requires
docker exec -it <container> bashto reach the framework environment.2. In-instance README and GitHub README disagree on what the hello-world IS
Pre-deploy research fetched the GitHub README, which positions the Ant RL training task as the canonical first-run example. The README rendered inside the deployed instance positions
create_empty.pyas the first-run example instead. Both demos work; both make sense as introductions. But a new user has no way to know which "first step" to follow, especially if they read the GitHub version before deploying and then the in-instance version after.Proposed fix
Pick one canonical first-run example and use it consistently across both READMEs. Or cross-link with a note: "if you're reading this in the deployed instance, run
create_empty.pyfirst to verify streaming; if reading on GitHub before deploying, here's the high-level overview of both demos."3. Web VS Code (code-server) opens a generic Microsoft walkthrough as the first tab, not the launchable's README
When the deploy completes and the user opens the web VS Code URL, the first tab is the generic "Get Started with VS Code for the Web" walkthrough (theme picker, command palette intro). The launchable's
README.md, which contains the actual first-run instructions, is not surfaced until the user manually closes the walkthrough and opens it from the file tree.For a paid first-time launchable, the first-impression tab being "unrelated VS Code tutorial" rather than "here's what to do in this Isaac Sim environment" is a wrong default.
Proposed fix
In the launchable's startup script (or code-server config), dismiss the generic walkthrough by default and open
README.mdin preview mode as the initial tab. Both are code-server settings changes.Notes
[N] app readylog line being buried in ~200 lines of startup noise is upstream Isaac Sim behavior and harder to address from the launchable side, so noting separately rather than including here.ISAAC_NUCLEUS_DIR = Nonewith bareSimulationApp,prim_pathneeding an Xform parent) traces back to my own deviations from the canonical IsaacLab pattern, so not filing those here either.Happy to break any of the above into separate issues if that's preferred.