Skip to main content
Glama
fixed-width

glass

by fixed-width
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust

glass_start

Build and launch an app, then locate its window and return geometry (position and size) for UI automation.

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for build and app; defaults to the server directory.
envNoExtra {KEY: VALUE} environment for build and app. Android applies it only to the host build, not the app.
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"].
a11yNoEnable the private accessibility bus (default true). False skips it for canvas-only apps. Linux only; other backends read accessibility ambiently.
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_hintNoSelect a window by title/class, including process handoffs. Omit for the first window owned by the process or a followable descendant.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
  2. 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\"]`."
  3. 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"
  4. Addedv1.1.0
  5. Removedv1.0.3
  6. Addedv1.0.2

TDQS

A4.4/5.0
Behavior4/5

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

The description discloses that accessibility is enabled by default and that window_hint can locate handoffs—not obvious from the schema alone. It also notes that backend and containment choices are in the parameters, which adds behavioral context. The annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are not contradicted; the tool performs actions but is not destructive. The description adds useful nuance beyond the annotations.

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?

The description is three sentences and front-loaded with the core action (build, launch, locate) and return value (window geometry). It avoids unnecessary fluff. The only minor deduction is that the last sentence is somewhat vague ('See parameters for backend and containment choices') rather than giving specific guidance, but it's still efficient overall.

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

Completeness4/5

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

With 9 parameters, a nested object, and no output schema, the description does not detail return format, error cases, or platform specifics beyond its brief mention. However, the schema carries most of the parameter documentation, and the description covers the high-level workflow. It could be more complete by explaining what 'returns window geometry' implies in practice (e.g., coordinates, size), but given the schema's richness, this is adequate.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds meaning by summarizing how window_hint works (select among windows or locate a handoff) and pointing to backend and containment choices. It does not enumerate each parameter, but it gives a high-level semantic framework that helps agents understand the tool's logic without reading every schema detail. Given the schema is already thorough, this adds value without redundancy.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Build, launch and locate an app; returns window geometry.' It uses specific verbs and a clear resource (an app), and mentions returning window geometry. It also distinguishes itself from siblings like glass_select_window and glass_window by focusing on the full build/launch/locate workflow.

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

Usage Guidelines4/5

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

The description provides context on when to use this tool (to build, launch, and locate an app) and hints at alternatives via window_hint for selecting windows or handoffs. However, it does not explicitly state when not to use it or name specific sibling tools as alternatives, such as glass_select_window for pure window selection.

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

Deploy Server

Other Tools