glass_start
Launch a native GUI app and get its window geometry. Use optional title/class hints to locate the right window when several appear or the app hands off to another process.
Instructions
Build, launch, and locate a native GUI app; returns its window geometry. Choose a backend with the backend param (defaults to the host). The accessibility tools are enabled by default; pass a11y:false to skip the accessibility bus for canvas/pixel-only apps. Optional window_hint ({ title?, class? }) picks the right window when several appear, or locates one the launched process hands off to another process.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for both `build` and the launched app; omit to inherit the server's own. | |
| env | No | Extra environment variables, as a `{ "KEY": "VALUE" }` object. They reach the launched app on the desktop backends and on `ios`; on `android` they configure the `build` command on the host only, since an app launched by `am start` is forked from zygote and never sees the shell's environment. | |
| run | Yes | What to launch, then its arguments. `run[0]` is the executable on a desktop backend, an `.app` path or bundle id on `ios`, and a `package/.Activity` component — optionally with an `.apk` to install first — on `android`. `run[1..]` are the app's own arguments; `android` has no argument vector to put them in and returns an error rather than ignoring them. | |
| a11y | No | Spawn a private accessibility (AT-SPI) bus so `glass_a11y_snapshot` / `marks` / `set_value` / `click_element` / `wait_for_element` work against this app. **On by default** — the accessibility path is the cheap, low-token way to drive a UI, so it is available unless you opt out. Pass `false` to skip the bus for canvas/pixel-only apps (it spawns extra processes). Effective on Linux only; other backends read accessibility ambiently and ignore this flag. | |
| build | No | Optional shell command to run (in `cwd`) before launching. | |
| backend | No | Backend to launch under: `"x11"` or `"wayland"` (Linux), `"windows"` (on a Windows host), `"macos"` (on a macOS host), `"android"` (an AVD emulator, any host), or `"ios"` (an iOS Simulator, macOS host). Omit for the server default (`GLASS_BACKEND`, else `windows` on Windows, `macos` on macOS, else x11). | |
| sandbox | No | Containment level for the launched app: `"default"` (filesystem/process containment, network on), `"strict"` (also no network), or `"off"` (no containment). Omit for the server default (`GLASS_SANDBOX`, else `default`). An operator-set floor (`GLASS_SANDBOX_FLOOR`) may raise an omitted level, and refuses an explicit level requested below it. | |
| timeout_ms | No | How long to wait for the app's window to appear before failing the launch (default 10000ms). Does not bound `build`. | |
| window_hint | No | Optional `{ title?, class? }` to disambiguate which window is the app's when more than one appears, or to find a window the launched process hands off to an unrelated process. Omit to take the first window owned by the launched process or a descendant it can follow. |