> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open an app

> Focus a window, launch an app, or open a file

Focus a window, launch an installed app, or open a file with the app that owns it. Start the display first.

CLI and cURL examples use `$RT` with the display already started ([Screen](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/screen.md#start-the-display)).

## Focus a window

`windows` returns `{windows: [...], focused}` — `focused` is the focused
window's `id`; each entry carries `id`, geometry (`x`, `y`, `w`, `h`),
`title`, `window_class`, `instance`, `desktop` (virtual-desktop index),
`focused`, and `states` (window-manager flags). `window_class` filters by
class substring. `window_op` takes the window `id` and an `op` — `focus`,
`close`, `raise`, `lower`, `move` (with `x`/`y`), `resize` (with `w`/`h`),
`maximize`, `unmaximize`, `minimize`, `fullscreen`, `unfullscreen` — and
returns the window's post-op record.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable(wm="openbox")          # a WM gives you real windows
bid = sandbox.browser.open(url="https://example.com")["browser_id"]  # headed

wins = sandbox.desktop.windows()
for w in wins["windows"]:
    print(w["id"], w["window_class"], w["title"], w["focused"])

wid = wins["windows"][0]["id"]
sandbox.desktop.window_op(wid, "maximize")
sandbox.desktop.move_window(wid, 100, 100)       # convenience: op + x,y
sandbox.desktop.resize_window(wid, 1024, 768)    # convenience: op + w,h
sandbox.desktop.focus_window(wid)
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable({ wm: 'openbox' }); // a WM gives you real windows
await sandbox.browser.open({ url: 'https://example.com' }); // headed

const wins = await sandbox.desktop.windows();
for (const w of wins.windows) {
  console.log(w.id, w.windowClass, w.title, w.focused);
}

const wid = wins.windows[0].id;
await sandbox.desktop.windowOp(wid, 'maximize');
await sandbox.desktop.windowOp(wid, 'move', { at: { x: 100, y: 100 } });
await sandbox.desktop.windowOp(wid, 'resize', { size: { w: 1024, h: 768 } });
await sandbox.desktop.windowOp(wid, 'focus');
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop windows "$RT"                # --class filters
gravixlayer runtime desktop window-op "$RT" 42 maximize
gravixlayer runtime desktop window-op "$RT" 42 move --x 100 --y 100
gravixlayer runtime desktop window-op "$RT" 42 resize --w 1024 --h 768
gravixlayer runtime desktop window-op "$RT" 42 focus
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS "$API/agents/runtime/$RT/display/windows" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS -X POST "$API/agents/runtime/$RT/display/windows/op" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":42,"op":"maximize"}'

curl -sS -X POST "$API/agents/runtime/$RT/display/windows/op" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":42,"op":"move","x":100,"y":100}'
```

| `op` | Extra fields | Effect |
| - | - | - |
| `focus` | — | Give the window input focus |
| `close` | — | Close the window |
| `raise` / `lower` | — | Reorder it in the stack |
| `move` | `x`, `y` | Move to coordinates |
| `resize` | `w`, `h` | Resize to pixels |
| `maximize` / `unmaximize` | — | Maximize or restore |
| `minimize` | — | Iconify |
| `fullscreen` / `unfullscreen` | — | Toggle fullscreen |

Window ops need a window manager — pass `wm` at `enable` (or run a desktop
template, which ships one). Without a WM, `windows` lists what the X server
maps but placement ops have no effect.

## Launch an app

`apps` lists the applications the template registered — each entry is
`{id, name, exec, icon, categories}` (a freedesktop entry). `launch_app` starts one by
its `apps()` id; `uri` substitutes into the app's exec line (open a URL in
the registered browser, a file in the editor, …). `wait_window` blocks until
a new top-level window maps — the launch-then-act pattern — and returns
`{pid, window_id, app}`; `timeout_ms` caps the wait (default 10000 when
waiting).

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()

for a in sandbox.desktop.apps()["apps"]:
    print(a["id"], a["name"])

r = sandbox.desktop.launch_app("chromium", uri="https://example.com",
                               wait_window=True)
print(r["pid"], r["window_id"])
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();

for (const a of await sandbox.desktop.apps()) {
  console.log(a.id, a.name);
}

const r = await sandbox.desktop.launchApp('chromium', {
  uri: 'https://example.com',
  waitWindow: true,
});
console.log(r.pid, r.windowId);
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop apps "$RT"
gravixlayer runtime desktop launch "$RT" chromium --uri https://example.com --wait-window
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS "$API/agents/runtime/$RT/display/apps" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS -X POST "$API/agents/runtime/$RT/display/apps/launch" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app":"chromium","uri":"https://example.com","wait_window":true,"timeout_ms":10000}'
```

## Open a file

`open` hands a file path or URL to its registered handler — a URL to the
default browser, a PDF to the document viewer, a text file to the editor —
and returns `{pid, window_id, app, mime}` (`mime` names the detected type,
`window_id` is set when `wait_window` resolved one). Use it when you want
the platform's routing rather than picking the app yourself.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()
sandbox.file.write("/workspace/report.txt", "quarterly numbers\n")

r = sandbox.desktop.open("/workspace/report.txt", wait_window=True)
print(r["app"], r["window_id"], r["mime"])
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();
await sandbox.file.write('/workspace/report.txt', 'quarterly numbers\n');

const r = await sandbox.desktop.open('/workspace/report.txt', { waitWindow: true });
console.log(r.app, r.windowId, r.mime);
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop open "$RT" /workspace/report.pdf --wait-window
gravixlayer runtime desktop open "$RT" https://example.com --wait-window
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/open" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com","wait_window":true,"timeout_ms":10000}'
```

## Use the window that opened

* A `wait_window` launch or open is how you chain into input: the returned
  `window_id` is the new top-level window, ready for `window_op` or a
  screenshot cropped to its geometry.
* `apps` reflects the template — a template without registered desktop
  entries returns an empty list, and `launch_app` then returns `404` for
  unknown ids.
* For web work prefer `browser.open` — it manages the browser's lifecycle,
  tabs, and headless mode. `open`/`launch_app` are for everything else.

## Endpoints

| Method | Path | Description |
| - | - | - |
| GET | `/v1/agents/runtime/{runtime_id}/display/windows` | List top-level windows |
| POST | `/v1/agents/runtime/{runtime_id}/display/windows/op` | Focus, close, move, resize, maximize… a window |
| GET | `/v1/agents/runtime/{runtime_id}/display/apps` | List installed applications |
| POST | `/v1/agents/runtime/{runtime_id}/display/apps/launch` | Launch an app by id |
| POST | `/v1/agents/runtime/{runtime_id}/display/open` | Open a file path or URL with its handler |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.