Skip to main content
Glama

glass_start

Build and launch native GUI apps, locate the target window by title or class, and return its geometry to enable GUI interaction and debugging.

Instructions

Build, launch and locate an app; returns window geometry. Accessibility is enabled by default. window_hint can select among windows or locate a handoff to another process. See parameters for backend and containment choices.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "run": "<run>"
    },
    "name": "glass_start"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoWorking directory for build and app; defaults to the server directory.
envNoExtra environment for build and app. Android applies it only to the host build.
runYesDesktop: [executable, args...]. iOS: [.app or bundle ID, args...]. Android: [apk?, package/.Activity] in either order, e.g. ["/absolute/path/app.apk", "com.example.app/.MainActivity"].
a11yNoLinux only. Enable the private accessibility bus (default true).
buildNoOptional shell command to run (in `cwd`) before launching.
backendNox11/wayland (Linux), windows (Windows), macos (macOS), android (any host), ios (macOS). Default: GLASS_BACKEND, else host default (x11 on Linux).
sandboxNodefault: filesystem/process containment, network on; strict: also no network; off: uncontained. Default GLASS_SANDBOX or default. GLASS_SANDBOX_FLOOR raises omitted levels and refuses explicit lower levels.
timeout_msNoWindow-publication timeout in ms (default 10000); does not bound build.
window_hintNoX11 and Windows: find a window by title/class, including process handoffs.
read_only_inputsNoLinux X11/Wayland only. Absolute paths to expose read-only in containment. Returns canonical paths and refuses protected paths.
accessibility_readerNoiOS only. axbridge reads WKWebView content and leaves automation mode enabled. Omit for the server default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.10.0
    • changedInput schema / $defs / WindowHintArgs / properties / class / description
      Previous value: -"Exact window-class match."New value: +"Exact class match on X11 and Windows. X11 also matches the WM_CLASS instance."
    • changedInput schema / $defs / WindowHintArgs / properties / title / description
      Previous value: -"Case-insensitive title substring; can locate a window handed off to an unrelated process."New value: +"X11: exact, case-sensitive WM_NAME. Windows: case-insensitive title substring."
    • changedInput schema / properties / a11y / description
      Previous value: -"Enable the private accessibility bus (default true). False skips it for canvas-only apps. Linux only; other backends read accessibility ambiently."New value: +"Linux only. Enable the private accessibility bus (default true)."
    • addedInput schema / properties / accessibility_reader
      Added value: +{
      +  "description": "iOS only. axbridge reads WKWebView content and leaves automation mode enabled. Omit for the server default.",
      +  "enum": [
      +    "ax",
      +    "axbridge",
      +    null
      +  ],
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • changedInput schema / properties / env / description
      Previous value: -"Extra {KEY: VALUE} environment for build and app. Android applies it only to the host build, not the app."New value: +"Extra environment for build and app. Android applies it only to the host build."
    • addedInput schema / properties / read_only_inputs
      Added value: +{
      +  "default": [],
      +  "description": "Linux X11/Wayland only. Absolute paths to expose read-only in containment. Returns canonical paths and refuses protected paths.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / run / description
      Previous value: -"Desktop: [executable, args...]. iOS: [.app-or-bundle-id, args...]. Android: [apk?, package/.Activity] in either order, e.g. [\"/absolute/path/app.apk\", \"com.example.app/.MainActivity\"]."New value: +"Desktop: [executable, args...]. iOS: [.app or bundle ID, args...]. Android: [apk?, package/.Activity] in either order, e.g. [\"/absolute/path/app.apk\", \"com.example.app/.MainActivity\"]."
    • changedInput schema / properties / window_hint / description
      Previous value: -"Select a window by title/class, including process handoffs. Omit for the first window owned by the process or a followable descendant."New value: +"X11 and Windows: find a window by title/class, including process handoffs."
  2. Changed10 schema fields changedv1.8.0
    • changedInput schema / $defs / WindowHintArgs / properties / class / description
      Previous value: -"Exact window-class match. Same purpose as `title` but more stable, since\nclass names rarely carry the dynamic prefixes/suffixes that titles do."New value: +"Exact window-class match."
    • changedInput schema / $defs / WindowHintArgs / properties / title / description
      Previous value: -"Case-insensitive substring matched against window titles. Used to pick the\nright window when several appear, and — since it ignores the process tree —\nto locate a window the launched process hands off to an unrelated process."New value: +"Case-insensitive title substring; can locate a window handed off to an unrelated process."
    • changedInput schema / properties / a11y / description
      Previous value: -"Spawn a private accessibility (AT-SPI) bus so `glass_a11y_snapshot` / `marks` /\n`set_value` / `click_element` / `wait_for_element` work against this app. **On by\ndefault** — the accessibility path is the cheap, low-token way to drive a UI, so it\nis available unless you opt out. Pass `false` to skip the bus for canvas/pixel-only\napps (it spawns extra processes). Effective on Linux only; other backends read\naccessibility ambiently and ignore this flag."New value: +"Enable the private accessibility bus (default true). False skips it for canvas-only apps. Linux only; other backends read accessibility ambiently."
    • changedInput schema / properties / backend / description
      Previous value: -"Backend to launch under: `\"x11\"` or `\"wayland\"` (Linux), `\"windows\"` (on a\nWindows host), `\"macos\"` (on a macOS host), `\"android\"` (an AVD emulator, any\nhost), or `\"ios\"` (an iOS Simulator, macOS host). Omit for the server default\n(`GLASS_BACKEND`, else `windows` on Windows, `macos` on macOS, else x11)."New value: +"x11/wayland (Linux), windows (Windows), macos (macOS), android (any host), ios (macOS). Default: GLASS_BACKEND, else host default (x11 on Linux)."
    • changedInput schema / properties / cwd / description
      Previous value: -"Working directory for both `build` and the launched app; omit to inherit the\nserver's own."New value: +"Working directory for build and app; defaults to the server directory."
    • changedInput schema / properties / env / description
      Previous value: -"Extra environment variables, as a `{ \"KEY\": \"VALUE\" }` object. They reach the launched app\non the desktop backends and on `ios`; on `android` they configure the `build` command on\nthe host only, since an app launched by `am start` is forked from zygote and never sees\nthe shell's environment."New value: +"Extra {KEY: VALUE} environment for build and app. Android applies it only to the host build, not the app."
    • changedInput schema / properties / run / description
      Previous value: -"What to launch: desktop `[executable, args...]`; iOS `[.app-or-bundle-id, args...]`;\nAndroid `[apk?, package/.Activity]` in either order, for example\n`[\"/absolute/path/app.apk\", \"com.example.app/.MainActivity\"]`."New value: +"Desktop: [executable, args...]. iOS: [.app-or-bundle-id, args...]. Android: [apk?, package/.Activity] in either order, e.g. [\"/absolute/path/app.apk\", \"com.example.app/.MainActivity\"]."
    • changedInput schema / properties / sandbox / description
      Previous value: -"Containment level for the launched app: `\"default\"` (filesystem/process\ncontainment, network on), `\"strict\"` (also no network), or `\"off\"` (no\ncontainment). Omit for the server default (`GLASS_SANDBOX`, else `default`).\nAn operator-set floor (`GLASS_SANDBOX_FLOOR`) may raise an omitted level, and\nrefuses an explicit level requested below it."New value: +"default: filesystem/process containment, network on; strict: also no network; off: uncontained. Default GLASS_SANDBOX or default. GLASS_SANDBOX_FLOOR raises omitted levels and refuses explicit lower levels."
    • changedInput schema / properties / timeout_ms / description
      Previous value: -"How long to wait for the app's window to appear before failing the launch\n(default 10000ms). Does not bound `build`."New value: +"Window-publication timeout in ms (default 10000); does not bound build."
    • changedInput schema / properties / window_hint / description
      Previous value: -"Optional `{ title?, class? }` to disambiguate which window is the app's when\nmore than one appears, or to find a window the launched process hands off to\nan unrelated process. Omit to take the first window owned by the launched\nprocess or a descendant it can follow."New value: +"Select a window by title/class, including process handoffs. Omit for the first window owned by the process or a followable descendant."
  3. Changed1 schema field changedv1.5.1
    • changedInput schema / properties / run / description
      Previous value: -"What to launch, then its arguments. `run[0]` is the executable on a desktop backend, an\n`.app` path or bundle id on `ios`, and a `package/.Activity` component — optionally with\nan `.apk` to install first — on `android`. `run[1..]` are the app's own arguments;\n`android` has no argument vector to put them in and returns an error rather than\nignoring them."New value: +"What to launch: desktop `[executable, args...]`; iOS `[.app-or-bundle-id, args...]`;\nAndroid `[apk?, package/.Activity]` in either order, for example\n`[\"/absolute/path/app.apk\", \"com.example.app/.MainActivity\"]`."
  4. Changed5 schema fields changedv1.2.0
    • addedInput schema / properties / cwd / description
      Added value: +"Working directory for both `build` and the launched app; omit to inherit the\nserver's own."
    • changedInput schema / properties / env / description
      Previous value: -"Extra environment variables for the launched app, as a `{ \"KEY\": \"VALUE\" }` object."New value: +"Extra environment variables, as a `{ \"KEY\": \"VALUE\" }` object. They reach the launched app\non the desktop backends and on `ios`; on `android` they configure the `build` command on\nthe host only, since an app launched by `am start` is forked from zygote and never sees\nthe shell's environment."
    • changedInput schema / properties / run / description
      Previous value: -"Program and arguments to launch; `run[0]` is the executable."New value: +"What to launch, then its arguments. `run[0]` is the executable on a desktop backend, an\n`.app` path or bundle id on `ios`, and a `package/.Activity` component — optionally with\nan `.apk` to install first — on `android`. `run[1..]` are the app's own arguments;\n`android` has no argument vector to put them in and returns an error rather than\nignoring them."
    • addedInput schema / properties / timeout_ms / description
      Added value: +"How long to wait for the app's window to appear before failing the launch\n(default 10000ms). Does not bound `build`."
    • removedInput schema / title
      Removed value: -"StartArgs"
  5. Addedv1.1.0
  6. Removedv1.0.3
  7. Addedv1.0.2

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it returns window geometry, accessibility is enabled by default, and it can locate a handoff to another process. It does not say what happens on build failure, whether the app persists after the call, or that glass_stop is the counterpart.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action and return value with no wasted preamble. The closing 'See parameters for backend and containment choices' is a mild deferral rather than substantive content, but it is compact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, nested-object launch tool with no output schema, the description covers return value and one key parameter but omits lifecycle details — whether the launched app stays running, what a failure yields, and how this relates to glass_stop. Adequate to invoke, incomplete for planning.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds modest value by explaining window_hint's window-selection and handoff-locating purpose and by pointing at backend/containment choices, but it defers the actual semantics of the remaining nine parameters to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause names concrete actions (build, launch, locate) plus the primary return value (window geometry), which is more specific than the tool name alone. It stops short of differentiating from siblings such as glass_list_windows or glass_select_window, which also deal with windows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not guidance relative to alternatives; an agent must infer that this is the entry point before screenshot/click tools. The only routing hint is that window_hint 'can select among windows or locate a handoff to another process', which explains one parameter rather than the tool's place in a workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.