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

# Computer Use

> See the runtime's screen, click and type on it, and open apps

See the runtime's screen, click and type on it, open apps, and watch it live. Use this for windows, dialogs, and pixels. For links and forms, use [Browser Use](https://docs.gravixlayer.ai/documentation/agentruntime/browser-use/overview.md).

## Requirements

Seeing and controlling the screen needs `desktop-small`. `desktop.enable` returns `400` on a template without a display. Checking or restarting desktop services needs the `desktop-small` template. `desktop.components` returns `404` otherwise.

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

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

# Start the display and capture the screen.
st = sandbox.desktop.enable(width=1920, height=1080)
print(st["enabled"], st["display"])   # True :0

shot = sandbox.desktop.screenshot()
print(shot["width"], shot["height"], shot["format"])

sandbox.kill()
```

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

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

// Start the display and capture the screen.
const st = await sandbox.desktop.enable({ width: 1920, height: 1080 });
console.log(st.enabled, st.display); // true :0

const shot = await sandbox.desktop.screenshot();
console.log(shot.width, shot.height, shot.format);

await sandbox.kill();
```

```bash CLI theme={null}
export GRAVIXLAYER_API_KEY=gl_sk_...
RT=$(gravixlayer runtime create -t desktop-small --wait --output json | jq -r '.runtime_id')

gravixlayer runtime desktop enable "$RT" --width 1920 --height 1080
gravixlayer runtime desktop screenshot "$RT" --out screen.png
gravixlayer runtime kill "$RT" -y
```

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

# Create a runtime on desktop-small, then use $RT for its id.
RT=$(curl -sS -X POST "$API/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"desktop-small","cloud":"aws","region":"us-east-1"}' \
  | jq -r .runtime_id)

curl -sS -X POST "$API/agents/runtime/$RT/display/enable" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width":1920,"height":1080}'

curl -sS -X POST "$API/agents/runtime/$RT/display/screenshot" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .data | base64 -d > screen.png

curl -sS -X DELETE "$API/agents/runtime/$RT" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

CLI and cURL examples on the following pages use `$RT` from the example above. Leave the runtime running until you are done. `desktop.enable` is safe to call first in every script — calling it again returns the display that is already running.

## Errors

| Status | What to do |
| - | - |
| `400` | The body is invalid, the display failed to start or is not enabled, or the window id does not exist. `enable` on a template without a display is also `400` — create the runtime with `desktop-small`. |
| `404` | No such app, file handler, or desktop component. |
| `408` | The call timed out. |
| `503` | Retry. |

Coordinates are screen pixels. `coordinate_space="screenshot"` on a click maps a point in a scaled screenshot back to the screen. Live view links expire after an hour. `role="watch"` makes a link that can see the screen and cannot type or click.

## Next

> [card] [Screen](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/screen.md)
>
> Start the display, capture it, and watch it live.

> [card] [Control](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/input.md)
>
> Click, type, and use the clipboard.

> [card] [Apps](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/windows-apps.md)
>
> Focus a window, launch an app, or open a file.

> [card] [Inspect](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/accessibility.md)
>
> Find a control by its name and press it.

> [card] [Record](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/recording.md)
>
> Record the screen and hand control to a person.

> [card] [Session](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/session.md)
>
> Check desktop services and restart one that failed.


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