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
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| size | No | 1440x900 | |
| command | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |