> ## 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.

# Repair the desktop

> Check desktop services and restart one that failed

Check that the desktop is healthy, restart a service that failed, and read its log. Use this before you drive the screen, and when a window manager or panel has crashed, without creating a new runtime.

CLI and cURL examples use `$RT` for a desktop template ([Overview](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/overview.md#requirements)). On any other template `components` returns `404`.

## Check the desktop

`components` returns `{present, display, user, components: [...]}` —
`present` says the image ships a desktop session, `display`/`user` name its
display and user, and each entry is
`{name, unit, active, sub, result, restarts, started_usec}` — `name` is the
descriptor key the other calls accept, `unit` the resolved service name,
`active`/`sub`/`result` the service state, `restarts` the restart count.

`component` with `op: start | stop | restart` acts on one and returns its
post-op record `{name, unit, active, sub, result}`. The SDKs also expose
`start_component`/`stop_component`/`restart_component` (`startComponent`,
`stopComponent`, `restartComponent`).

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

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

st = sandbox.desktop.components()
print(st["present"], st["display"], st["user"])
for c in st["components"]:
    print(c["name"], c["unit"], c["active"], c["sub"], c["restarts"])

sandbox.desktop.restart_component("wm")
print(sandbox.desktop.component("wm", "start"))
sandbox.kill()
```

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

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

const st = await sandbox.desktop.components();
console.log(st.present, st.display, st.user);
for (const c of st.components) {
  console.log(c.name, c.unit, c.active, c.sub, c.restarts);
}

await sandbox.desktop.restartComponent('wm');
console.log(await sandbox.desktop.component('wm', 'start'));
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop components "$RT"
gravixlayer runtime desktop restart "$RT" wm
gravixlayer runtime desktop start "$RT" wm
gravixlayer runtime desktop stop "$RT" wm
```

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

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

curl -sS -X POST "$API/agents/runtime/$RT/desktop/component" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"wm","op":"restart"}'
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Component key from `components` (or its unit name) |
| `op` | string | Yes | `start`, `stop`, or `restart` |

## Read a service log

`logs` pages a component's journal: pass `name`, get `{entries, cursor}`
back — each entry `{usec, unit, priority, message, identifier}` with `usec`
the realtime timestamp and `priority` the syslog level. Feed the returned
`cursor` into the next call for the following page; `""` reads the tail.
`max` (`max_entries` in Python, `--max` in the CLI) caps the page
(default 200, cap 1000) and `priority="err"` filters to errors.

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

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

page = sandbox.desktop.logs("session", max_entries=100)
for e in page["entries"]:
    print(e["priority"], e["message"])

while page["cursor"]:                       # drain until caught up
    page = sandbox.desktop.logs("session", cursor=page["cursor"])
    for e in page["entries"]:
        print(e["message"])
sandbox.kill()
```

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

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

let page = await sandbox.desktop.logs('session', { max: 100 });
for (const e of page.entries) {
  console.log(e.priority, e.message);
}

while (page.cursor) {                       // drain until caught up
  page = await sandbox.desktop.logs('session', { cursor: page.cursor });
  for (const e of page.entries) console.log(e.message);
}
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop logs "$RT" session --max 100
gravixlayer runtime desktop logs "$RT" session --priority err
gravixlayer runtime desktop logs "$RT" session --cursor "$CURSOR"   # next page
```

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

curl -sS -X POST "$API/agents/runtime/$RT/desktop/logs" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"session","max":100}'

curl -sS -X POST "$API/agents/runtime/$RT/desktop/logs" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"session","priority":"err"}'
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Component key from `components` (or its unit name) |
| `cursor` | string | No | Resume cursor from the previous page — `""` reads the tail |
| `max` | int | No | Entries per page (default 200, cap 1000) |
| `priority` | string | No | `err` filters to priority ≤ err; empty returns all |

## Restart what failed

* `components` is the health check that means something: a component with
  `active: "failed"` (or one that fails to resolve — it reports
  `active: "error"` with the reason in `sub`) is what to `restart`, and
  `logs` tells you why it failed.
* Stopping the session's display component takes the display with it —
  `desktop.enable` brings a fresh one back.
* Component names come from the template's desktop descriptor; a name that
  matches neither a descriptor key nor a unit returns `404`.

## Endpoints

| Method | Path | Description |
| - | - | - |
| GET | `/v1/agents/runtime/{runtime_id}/desktop/status` | Session + component states |
| POST | `/v1/agents/runtime/{runtime_id}/desktop/component` | `start` / `stop` / `restart` a component |
| POST | `/v1/agents/runtime/{runtime_id}/desktop/logs` | Page a component's journal |


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