Modes

The iwsdk CLI owns the browser launch and AI session settings. You can start a workspace without selecting an AI mode, or explicitly select collaborate or agent.

All three sessions open the managed browser by default. The managed workspace contains both Runtime and Editor views. IWSDK suppresses Vite’s separate browser launch while the workspace is enabled.

Run:

npx iwsdk dev up

This is the default manifest-first CLI session. It starts a headed, open managed workspace without assigning an AI mode. Use it for ordinary development, for inspecting the native Editor, or before choosing how an agent should participate.

You can still configure an MCP adapter independently. The absence of --ai-mode means the CLI has not applied the agent or collaborate behavior profile.

Run:

npx iwsdk dev up --ai-mode collaborate

Collaborate mode keeps the managed browser visible and resizable, and it enables DevUI. You and the agent share the same browser session, so you can watch tool-driven changes and use the browser directly.

Screenshots are downscaled when necessary to fit the configured screenshot bounds. Browser resizing does not change the selected mode.

Run:

npx iwsdk dev up --ai-mode agent

Agent mode launches a headless managed browser, disables DevUI, and uses a fixed viewport. The default viewport is 800 by 800 pixels. Set both dimensions when you need a repeatable alternative:

npx iwsdk dev up --ai-mode agent \
  --screenshot-width 1280 \
  --screenshot-height 720

Agent mode is appropriate for unattended execution and deterministic screenshots. A human can still inspect status, logs, and output artifacts from the command line.

Mode selection belongs to the developer who starts the session. An agent should not silently restart a collaborate session as an agent session, or change a headed session to headless. Start or restart the CLI with the requested mode when the workflow changes.

The CLI rejects incompatible combinations:

It also rejects any AI mode other than agent or collaborate.

Use --open or --no-open to control whether the managed browser starts:

npx iwsdk dev up --no-open

--no-open is a deliberate server-only state. The development server can be ready, but every iwsdk-runtime tool call remains unavailable because no managed browser tab is registered. This includes scene, UI, XR, browser, and ECS tools. Schema inspection with npx iwsdk mcp inspect remains available; use npx iwsdk dev status to distinguish server readiness from browser command readiness.

When the managed browser is open, the workspace provides Runtime and Editor views in the same window. If you also want a separate browser, open the runtime URL yourself.

The legacy iwsdkDev({ai: {}}) form defaults its AI mode to collaborate. New manifest-first projects should use bare iwsdkDev() and select the session with iwsdk dev up flags.