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

# Browsers and computers

> Give an agent a cloud browser for websites and portals, and computers you link with the desktop app for desktop apps. It uses them only when an answer needs them.

An agent answers from its files and tools when it can. When the answer or the fix lives in a website or a desktop app with no API, it runs a **task** there: on its own **cloud browser**, or on one of your **computers**. You choose what it may use in its `resources`:

```json theme={null}
"resources": {
  "browser": { "enabled": true, "start_url": "https://portal.example.com/orders", "keep_logins": true },
  "computers": [
    { "type": "computer", "id": "K7QM-24XP" },
    { "type": "pool", "id": "pool_8fK2mQ0aLp4x" }
  ]
}
```

| Field | What it does |
| - | - |
| `browser.enabled` | `true`: the agent can run browser tasks (`run_browser_task`). Off by default. |
| `browser.start_url` | Where its browser opens: an absolute `http` or `https` address. Empty: a blank page, and the agent opens what it needs. |
| `browser.keep_logins` | `true`: its next browser opens signed in to the sites it used. See [sign-ins](#sign-ins). |
| `computers` | Up to 50 linked computers (`{ "type": "computer", "id": "<its code>" }`) and pools (`{ "type": "pool", "id": "pool_…" }`) for its desktop tasks (`run_desktop_task`). Sending it replaces the whole list. |

Set them in the console on the agent's **Resources** tab, or send `resources` with any agent change: `POST /v1/agents`, `PATCH /v1/agents/{agent_id}` (publishes it), or `PATCH /v1/agents/{agent_id}/draft`. Only the keys you send change; `"browser": null` turns the browser off, and `"resources": null` resets both. Like every agent setting, resources are versioned, and a conversation uses the version each of its turns runs.

```bash theme={null}
curl -X PATCH https://guidinghand.ai/v1/agents/support \
  -H "Authorization: Bearer $EAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resources": { "browser": { "enabled": true, "start_url": "https://portal.example.com/orders" } } }'
```

What the agent may do there is set by its [guardrails](https://docs.guidinghand.ai/concepts/guardrails.md): which sites and apps it may use, which steps wait for your team's approval, and what it never does.

## Cloud browsers

A cloud browser is a Chromium that Eager runs for you, with nothing to install. It's what most agents use: carrier portals, order systems, vendor support sites, your own back office.

* **The agent's site rules are enforced inside the browser.** Every page and frame it opens is checked against the agent's `sites` [guardrails](https://docs.guidinghand.ai/concepts/guardrails.md) before it loads. Private and intranet addresses, `file:` and other non-web addresses never open, downloads are refused and file pickers don't open.
* **The agent opens addresses itself** (it has an `open_url` tool: the browser has no address bar on screen), and every task is [recorded](https://docs.guidinghand.ai/concepts/recordings.md) like any other.
* **It runs on Browserbase**, a cloud browser provider and one of Eager's subprocessors. Browserbase records it as a video, which the task's replay in the console plays once the browser has closed (the agent's screenshots play until then); it keeps the video 30 days, and doesn't record when your organization turns screen recording off. The browser presents as Chrome on Windows. Some sites refuse traffic from cloud providers or show a captcha: the agent can't get past those, and [your team can take control](#signing-in-for-the-agent) to deal with them.
* **There's no separate charge.** Tasks on a browser are billed for their tokens, like any task. See [Billing](https://docs.guidinghand.ai/concepts/billing.md).

An org can have **2 cloud browsers open at once**, across all its conversations and sessions. Ask us to raise it.

### Browsers in conversations

Each conversation gets its own browser, the first time its agent runs a browser task, at the agent's `start_url`. Later tasks in the conversation use the same browser, so pages and sign-ins carry from one to the next. The conversation's `session_id` is the browser's session, so it also shows in `GET /v1/sessions` (with `computer: "browser"`) and under **Computers → Sessions** in the console.

* It closes after **10 minutes without a task**, and the next task opens a new one at the start page (signed in, with `keep_logins`).
* When the org is at its limit, the agent makes room by closing another conversation's browser that has sat idle for 2 minutes or more, never one with a task running or one your team opened. If there's still no room, it waits up to a minute, then tells the person it couldn't open the site.
* You watch its tasks live in the console's chat, and the stream's `task.started` event has a `live_url` for each. See [tasks from a conversation](https://docs.guidinghand.ai/concepts/conversations.md#tasks-from-a-conversation).

### Sign-ins

Some sites need signing in. With `keep_logins` on, the agent's cookies are saved, encrypted, after each task and when its browser closes, and put back in its next browser. Off, every browser starts signed out.

> [!WARNING]
>
> Kept sign-ins belong to the agent, not to one conversation. Once someone signs in to a site in an agent's browser with `keep_logins` on, every conversation and session of that agent runs signed in as that account. Use an account made for the agent, with only the access it needs. Turning `keep_logins` off and publishing deletes the saved cookies.

#### Signing in for the agent

The agent never types a password. When a page needs signing in during a conversation's task, the task stops and says so (on a [browser session of your own](#a-browser-session-of-your-own), it asks your team to take control instead, and waits). Sign in for it between tasks: open the browser's session in the console (**Computers → Sessions**), click **Take control**, sign in, and hand it back. With `keep_logins` on, the sign-in is kept for the agent's next browsers.

With the API, `POST /v1/sessions/{session_id}/input` sends clicks, typing and keys to a browser, then returns its screen. It works only when no task is running there (or the task waits on a question); otherwise it's a `409` with `code: "agent_working"`. What you type isn't recorded, and the [audit log](https://docs.guidinghand.ai/concepts/audit-log.md) says who took control and how many actions they sent, never what they typed.

### A browser session of your own

To run a single task on a cloud browser outside a conversation (a back-office job from your own code, say), make a session with `"computer": "browser"`:

```bash theme={null}
curl https://guidinghand.ai/v1/sessions \
  -H "Authorization: Bearer $EAGER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "agent_id": "orders", "computer": "browser", "start_url": "https://shop.example.com/orders" }'
```

It answers once the browser is connected (a few seconds), with `computer: "browser"` and no `invite_url`. Then [start tasks](https://docs.guidinghand.ai/guides/single-task.md) on it as on any session. Nobody sits at it, so a task's questions and approvals go to your team. It closes after 10 minutes without a task (status `disconnected`) and opens again with the next task, or with `POST /v1/sessions/{session_id}/open`.

At the org's limit, making or opening one is refused with `409` and `code: "browser_limit"` until a browser closes; it doesn't close a conversation's browser for you. If no cloud browser is free, it's a `503` with `code: "no_browser"`.

## Linked computers

For desktop apps (a point-of-sale back office, a carrier's Windows client, anything with no web version), link a Mac or Windows PC of your own, or a virtual machine you run (in your cloud or on a server, signed in to its desktop), with the desktop app. Want us to host the virtual machine instead? Hosted VMs are in early access: write to [sales@guidinghand.ai](mailto:sales@guidinghand.ai). A linked computer belongs to your org, starts with the computer, reconnects on its own, and has nobody at it: the agent's desktop tasks run there unattended.

To link one:

1. In the console, open **Computers → Link a computer**, name it ("Front desk PC"), and get a link code. Or `POST /v1/computers` with `{ "name": "Front desk PC" }`, which returns the computer with its `code`.
2. On that computer, install the desktop app ([Mac](https://guidinghand.ai/download/mac) or [Windows](https://guidinghand.ai/download/windows)) and enter the code. The code works for 72 hours. The app says it's linked, and opens at login from then on.
3. Add it to an agent's `resources.computers`, on its own or in a [pool](#pools).

```json theme={null}
{
  "object": "computer",
  "id": "K7QM-24XP",
  "name": "Front desk PC",
  "code": null,
  "linked_at": "2026-10-18T09:12:40.118Z",
  "online": true,
  "busy": false,
  "os": "windows",
  "device_name": "FRONTDESK-01",
  "app_version": "1.0.36",
  "last_seen_at": "2026-10-18T10:02:11.000Z",
  "created_at": "2026-10-18T09:10:03.552Z",
  "pools": ["pool_8fK2mQ0aLp4x"]
}
```

* `id` is the computer's code, which an agent's `resources.computers` names. `code` is the link code until the app has linked, then `null`.
* `online` says its app is connected now, and `busy` that it's running a task.
* `GET /v1/computers` lists them by name, a page at a time (`q` searches names). `PATCH /v1/computers/{id}` with `{ "name" }` renames one. `DELETE /v1/computers/{id}` unlinks it: a running task stops, the app can't reconnect, and it leaves its pools. Its task history stays.
* Anyone in the org can list computers; linking, renaming and unlinking need the admin role or an API key.

### Pools

A pool is a named set of computers, so an agent can use whichever is free:

```bash theme={null}
curl https://guidinghand.ai/v1/computer_pools \
  -H "Authorization: Bearer $EAGER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Back office PCs", "computer_ids": ["K7QM-24XP", "R2WN-77KD"] }'
```

`GET`, `PATCH` (with `name` and the whole `computer_ids` list) and `DELETE` work on `/v1/computer_pools/{pool_id}`. Deleting a pool leaves its computers linked.

### How a desktop task picks a computer

The agent's computers are its `resources.computers` in order, each pool expanded to its computers. A desktop task takes the first one that's online and not running a task, and two tasks never take the same one. If none is free, it waits up to a minute, then tells the agent no computer was free. So list the computers you'd like used first, first.

A desktop task runs like a browser task: a worker with the agent's goal, tools, guardrails and procedure, nobody to ask, its approvals asked in the conversation, where the reply pauses until they're decided, when the agent is `supervised` (see [Approvals](https://docs.guidinghand.ai/concepts/conversations.md#approvals)). The task's conversation item and events name the `computer` it ran on. Linked computers need the desktop app 1.0.36 or later to start with the computer.

## Remote support on a customer computer

To work on a customer's own Mac or PC while they watch (remote support), send them an invite link instead: a [session](https://docs.guidinghand.ai/concepts/sessions.md) for one computer, where the customer can answer the agent's questions, approve its steps and press **Stop**. See [Run a task on a computer](https://docs.guidinghand.ai/guides/single-task.md).


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