> For the complete documentation index, see [llms.txt](https://docs.m-xr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.m-xr.com/marso-studio/plugins/m-xr-plugins/isaac-sim-add-on.md). # Isaac Sim add-on The Marso add-on brings Marso Studio into NVIDIA Isaac Sim. In Isaac Sim it's called **Marso Library**, and it does four things: * **Library**: browse your Studio projects and put their PBR assets on the stage as USD, upright, at real-world size and with physics * **Create**: make a new asset from a description or your own picture * **Sim Studio**: film your assets in physics and robot tests, rendered as videos * **Agent connection**: let the AI agents you use with the Marso MCP work in your Isaac Sim. Off until you switch it on. Only **Create** spends credits, from the same balance as the web app. Assets are always generated in Marso, not on your computer. ## What you'll need * **NVIDIA Isaac Sim 6.0 or newer**, on a computer with an NVIDIA RTX GPU. The add-on is tested with Isaac Sim 6.0.1 and 6.1.0 on Windows. * A Marso Studio account on a paid plan, or the trial. The add-on works through the Marso Studio API, which the Free plan doesn't include. See [Plans](/marso-studio/reference/credits-and-billing.md#plans). * Credits, for making new assets: see [Credits & billing](/marso-studio/reference/credits-and-billing.md). * An **API key**. The add-on authenticates with a key, not a login. * An internet connection. The robot tests in Sim Studio download NVIDIA's robot models the first time they run. ## 1. Create an API key 1. Log in to [marso.app](https://marso.app/). 2. Open **API Keys** in the left sidebar. 3. Under **New Key**, give the key a name ("Isaac Sim" is a sensible one) and click **Create Key**. 4. **Copy the key immediately.** It's shown only once. Keys begin `mxr_live_`. See [API access](/marso-studio/api/api-access.md) for managing and revoking them. > **Treat the key like a password.** Don't share it or commit it to source control. If it's ever exposed, revoke it in Studio and create a new one. ## 2. Install the add-on The add-on installs from Marso's extension registry, inside Isaac Sim. There's nothing to download by hand. 1. In Isaac Sim, open **Window → Extensions**. 2. Click the **menu icon** (three lines) next to the search box and choose **Settings**. 3. Under **Extension Registries**, click **+**, then double-click the new row and set: * **Name:** `Marso` * **URL:** `https://mxr-software.github.io/marso-isaacsim-registry` 4. Back in the extension list, search for **Marso** and open **Marso Library**. 5. Click **Install**, then switch it on. Tick **Autoload** so it starts every time Isaac Sim does. The Marso window opens beside the Content browser. Reopen it any time from **Window → Marso Library**. ### Starting Isaac Sim from a command line Add the registry and enable the add-on with these two arguments, where `N` is the next free registry slot: ``` --/exts/omni.kit.registry.nucleus/registries/N/url=https://mxr-software.github.io/marso-isaacsim-registry --enable marso.library ``` ## 3. Connect your account 1. In the Marso window, open the **Settings** tab. 2. Paste your key into **API key** and press **Check**. The note under the field shows which account you're connected as. If the `MARSO_API_KEY` environment variable is set, the add-on uses it whenever the field is empty. ## Putting assets on the stage With the **Library** tab open: 1. Pick a project on the left. Its thumbnails load when you open it. 2. Click an asset to select it. The **(i)** button opens its details: what it is, its materials, its real-world size and its physics. 3. Click **Add to Stage**, or drag a downloaded tile into the viewport to drop it where you point. An asset that isn't on your computer yet downloads first. 4. Press **Play** in Isaac Sim. Sim-ready assets fall and collide. Assets land upright and at real-world size. On a stage with no physics, the first one also adds a ground and a physics scene, so Play works straight away. Several assets added together land in a row, and **Settings → Adding to the stage** switches that to a grid or a stack. Undo removes them. **Download** and **Download all missing** fetch assets without adding them. The search box looks through names, types, materials and tags. The **Downloaded** tab lists everything on your computer and works offline. ### What the badges on a tile mean | Badge | Meaning | | ------------------------- | ------------------------------------------------------------------------ | | Sphere with a **USD** tag | A PBR model, downloaded as a USD file | | Sphere with an atom | **Sim-ready**: the file has a rigid body and colliders | | Green tick | Downloaded | | Amber circular arrows | A newer version is in Marso. **Update all** in the bottom bar fetches it | | Star | A favourite. Favourites and recently used assets sit above your projects | | Warning triangle | **Worth a look**: the details panel says why | ## Making a new asset With the **Create** tab open: 1. Describe one object and press **Generate Image**, or press **Import Image...** to use your own picture (PNG, JPEG or WebP, up to 5 MB). Importing is free. 2. Tick **Import onto stage when ready** if you want the asset on the stage as soon as it arrives. 3. Press **Create 3D Asset**. Marso builds the 3D mesh and predicts its PBR materials, then finishes the asset with a name, a description and physics. It takes a few minutes and carries on in the background while you work. The finished asset downloads by itself and appears in the Library under **Made in Isaac Sim**. In Marso Studio, you'll find it in a project called **IsaacSim\_AddOn**. Each step shows its cost and your balance before you press it. A step you can't afford offers **Top Up Credits** instead. See [Credits & billing](/marso-studio/reference/credits-and-billing.md) for what generation costs. If Isaac Sim closes part-way, the run picks up from the same step next time, so nothing is paid for twice. **Retry** carries on from a step that stopped or failed. ## Filming in Sim Studio Select one or more assets in the Library and press **Sim Studio**. Tick the tests you want, choose the quality (Preview up to 4K), the aspect (16:9, 9:16, 1:1 or 4:5) and branded or clean footage, then press **Render**. There are five physics tests (scale, drop, friction, wind and collision) and five robot tests that use NVIDIA's robot models. Rendering runs in a separate Isaac Sim, so you can keep working. Each run saves its videos, a results card for each test, a scene you can open and edit in Isaac Sim, and a report, in `Documents/Marso/Sim Studio` by default. For what each test does and its settings, open **Marso Library** in **Window → Extensions** and read its README. ## Connecting your AI agents Turn on **Settings → Agent connection → Connect to Marso Agents**, then add the Marso MCP to your chat app (ChatGPT, Codex or Claude) at `https://mcp.api.marso.app/mcp`. Agents signed in to the same Marso account can then put Marso assets on your stage and film them in Sim Studio, and the finished video appears in your chat. Isaac Sim connects out to the Marso MCP with your API key, so nothing listens on your computer. Agents can't change your settings or folders, use the Create tab, delete downloads or open files. To add Marso MCP to your chat app, see [Connect your agent](/marso-studio/mcp/connect-your-agent.md). For what agents can do here, see [Blender and Isaac Sim](/marso-studio/mcp/blender-and-isaac-sim.md). ## Files and folders | What | Where, by default | | -------------------------------------- | ------------------------------------------------------------------------ | | Downloaded assets | `Documents/Marso/Downloads` | | Thumbnails and the last synced listing | Your local app-data folder, under `Marso/IsaacSim/Cache`. Safe to delete | | Sim Studio videos | `Documents/Marso/Sim Studio` | Change the first two in **Settings → Storage**. > **Using the Blender add-on too?** Point its **Downloads Path** at the same folder and the two share downloads: anything one has downloaded shows as downloaded in the other. See [Blender add-on](/marso-studio/plugins/m-xr-plugins/blender-add-on.md). ## Keeping the add-on up to date When a new version is published, the Extension Manager offers it on the **Marso Library** page in **Window → Extensions**. ## Troubleshooting | What you see | What it means | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Marso** isn't in the extension list | Check the registry URL. It ends at `marso-isaacsim-registry`, with nothing after it, and Isaac Sim must be able to reach `mxr-software.github.io`. | | *Marso rejected the API key* | Copy the key again from marso.app, paste it into **Settings**, and press **Check**. | | *Your plan does not include this feature* | Your Marso Studio account is on the Free plan, or its trial has ended. The add-on needs a paid plan or the trial: see [Plans](/marso-studio/reference/credits-and-billing.md#plans). | | A tile says it has no USD package | The asset has no USD version in Marso yet, so it can't go on a stage. | | *The existing download could not be replaced* | The file is open in the stage. Remove it from the stage, then download again. | | *Not enough Marso credits for this step* | Top up at marso.app, then press **Retry**. The steps already done are kept. | | A robot test can't load the robot | The first run downloads NVIDIA's robot models, so it needs an internet connection. | | Thumbnails are missing | Press the refresh button in the Marso window's header. | Anything else, or a result that looks wrong: [Contact Support](/marso-studio/help-and-support/contact-support.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.m-xr.com/marso-studio/plugins/m-xr-plugins/isaac-sim-add-on.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.