---
title: "Remote browsers · Docs"
description: "Start a Donut Browser profile on a Windows, macOS or Linux machine in Donut's fleet and drive it over CDP from your computer. Plans, hours and API."
url: "https://donutbrowser.com/docs/remote-browsers/"
---

# Run profiles on remote machines

A remote session runs one of your profiles on a machine in Donut's fleet, with the profile's own operating system. Your computer can sleep, or run other work. The profile keeps its fingerprint, cookies and proxy. When the session ends, the remote machine uploads the changes and your computer downloads them before it opens the profile again.

Starting a remote session on demand needs Pro, Team or Enterprise. Solo can run [scheduled recipes](https://donutbrowser.com/docs/agent#schedules) and [Cookie Bot](https://donutbrowser.com/docs/cookie-bot) on the fleet, but cannot start a session by hand or from code. Sessions spend [remote hours](https://donutbrowser.com/docs/cookie-bot#remote-hours): 200 a month on Pro, and 200 for each paid seat on Team, shared.

## What a profile needs

- [Sync](https://donutbrowser.com/docs/sync) in **Regular Sync** mode. A remote machine cannot open an end-to-end encrypted profile.
- A fingerprint for Windows, macOS or Linux. The session runs on a machine with that system.
- No other session of the profile: the remote session holds the profile's lock.
- If the profile has a proxy or VPN, the remote machine must reach it. A proxy on `127.0.0.1` exists only on your computer.

## Start a session

Remote sessions start from code, an agent or a schedule:

- The local REST API: `POST /v1/profiles/{id}/run-remote`.
- Remote MCP, with the `remote` toolset. See [Remote MCP](https://donutbrowser.com/docs/remote-mcp#toolsets).
- A [scheduled recipe](https://donutbrowser.com/docs/agent#schedules) with **Remote fleet** as the target.

While a session runs, the profile shows **Running on a remote machine**. Stop the session to bring the profile back.

## Over the local API

```bash
# Start the profile on a machine of its own operating system
curl -sS -X POST http://127.0.0.1:10108/v1/profiles/<profile id>/run-remote \
  -H "Authorization: Bearer $DONUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
# {"profile_id":"…","session_id":"…","platform":"windows","status":"provisioning"}

# Poll until the session is ready
curl -sS http://127.0.0.1:10108/v1/remote-sessions/<session id> \
  -H "Authorization: Bearer $DONUT_API_KEY"
```

Attach Playwright through your desktop app. It relays the remote browser's CDP over the local API, so your script never needs your Donut account credential:

```js
import { chromium } from "playwright";

const browser = await chromium.connectOverCDP({
  endpointURL: `ws://127.0.0.1:10108/v1/remote-sessions/${sessionId}/cdp`,
  headers: { Authorization: `Bearer ${process.env.DONUT_API_KEY}` },
});
```

Other routes:

- `DELETE /v1/remote-sessions/{id}` stops the session and answers with the billed seconds.
- `GET /v1/remote-sessions` lists your sessions.
- `GET /v1/remote-hours` shows the hours used and left.
- `POST /v1/profiles/{id}/cloud-sync` turns on sync and says if the profile can run remotely.

`run-remote` answers `400` when the profile does not sync, `402` without a plan that includes automation, `409` when the profile is locked by another session, and `503` when no machine of that system is free. The URL must be `http`, `https` or `about:blank`.