Skip to main content
Glama

launch_app

Launches a GUI app in its own isolated Xephyr display and returns an instance ID for subsequent control tools.

Instructions

Launch a GUI app in its OWN new Xephyr display/window and return its instance id.

command is any shell command ('chromium', 'xterm', 'gimp', 'inkscape file.svg', …). Chromium-family browsers (chromium, google-chrome, brave, microsoft-edge, vivaldi, opera) automatically get X11 flags, a per-instance profile, downloads routed to files//, and a CDP debug port (needed by upload_file and browser()). Other GTK apps get D-Bus isolation so they render on this display, not the host.

Returns {"ok", "instance", "display", "name", "files_dir", "width", "height", "warnings": [...], "keyboard": {method, host_layout, verified}, "clipboard_sync": bool} — pass that instance id to every control tool. "keyboard" says how the window got the host's keyboard layout ("host-keymap" = exact copy, verified against the host; Xephyr alone maps AltGr as plain Alt, so a person could not type @ { } [ ] on Slovenian/German/… layouts); "clipboard_sync" is true when the per-instance host bridge runs (it mirrors text between the host and instance clipboards and keeps the keymap equal to the host's; GLOVEBOX_CLIPBOARD_SYNC=0 disables it — note that whatever the person copies on the host then becomes readable inside the sandbox). Neither affects the agent's own type_text/clipboard. Fails (isError) BEFORE anything starts if the command is empty/unparsable or size is not WxH; after that if Xephyr can't start on the host display (its log tail is quoted), the command doesn't exist, or the app exits immediately (its stderr tail is quoted; app_log(instance) has more) — the display is closed again in those cases. "warnings" lists what degraded: window manager (openbox) missing (Xephyr then ignores pointer motion, so clicks would land in the screen center), keymap copy or clipboard bridge failed. Each instance has its own cursor, so separate agents can drive separate instances in parallel; display numbers are allocated under a cross-process lock, so parallel launches don't collide. Never share one instance between agents. The window appears on GLOVEBOX_HOST_DISPLAY (default :0). Give the app a moment to draw (wait_for_stable / settle_ms) before the first screenshot. Instances outlive this server process unless GLOVEBOX_CLEANUP_ON_EXIT=1.

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": {
      "command": "<command>"
    },
    "name": "launch_app"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNo
sizeNo1440x900
commandYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.1/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so richly: automatic X11 flags and per-instance profile for Chromium-family, D-Bus isolation for GTK apps, per-instance cursor enabling parallel agents, display allocation under a cross-process lock, and instance lifetime outliving the server unless GLOVEBOX_CLEANUP_ON_EXIT=1. It also enumerates the exact failure contract — fails before anything starts on empty/unparsable command or malformed size, and after that on Xephyr failure, missing command, or immediate exit, with the display closed again — plus what each 'warnings' entry means and the host clipboard-exposure implication.

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?

Purpose and return contract are front-loaded, and most sentences carry real information (failure modes, warnings, parallelism, lifecycle). It is nonetheless a dense, long block with heavy parentheticals about keymaps and clipboard sync that could be tightened without losing decision-relevant content.

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

Completeness5/5

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

For a tool that spawns an isolated display, starts arbitrary processes, and hands back an instance id to every downstream control tool, the description covers creation, failure, degradation warnings, concurrency, and cleanup behavior. Return-field enumeration duplicates the existing output schema, but that is redundancy rather than incompleteness.

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 description coverage is 0%, so the description must compensate. It fully characterizes `command` (any shell command, with examples and the automatic browser handling) and implies `size`'s format via 'Fails … if `size` is not WxH', but the `name` parameter is never explained or tied to the returned 'name' field. Two of three parameters get some treatment, one gets none.

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?

Opens with a specific verb and resource — 'Launch a GUI app in its OWN new Xephyr display/window and return its instance id' — which tells an agent exactly what is created and what comes back. The only gap is that it never contrasts itself with the sibling 'start_app', so an agent facing both must guess which launcher to pick.

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?

Gives concrete downstream guidance: 'pass that instance id to every control tool', 'Give the app a moment to draw (wait_for_stable / settle_ms) before the first screenshot', and 'Never share one instance between agents'. It also explains why CDP matters for upload_file and browser(). It stops short of explicit when-to-use/when-not-to-use routing versus the other launch sibling.

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