# Remote Firefox Browser in the Cloud – noVNC Desktop Session (`rl1987/firefox-sandbox`) Actor

Open a link and you are driving a real Firefox on a Linux desktop in the cloud, streamed into your own browser tab over noVNC — nothing to install, no extension, no VM to provision. Set the start URL, screen size and a VNC password, and route Firefox through Apify Proxy or your own proxy.

- **URL**: https://apify.com/rl1987/firefox-sandbox.md
- **Developed by:** [R.L.](https://apify.com/rl1987) (community)
- **Categories:** Developer tools, Other
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 6 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Remote Firefox Browser in the Cloud – noVNC Desktop Session

A live, remote-controlled Firefox browser you drive from your own browser window — no local install, no extension, no VM to provision. Start the Actor, open the link, and you are looking at a real Linux desktop with Firefox running on it, streamed to your tab over noVNC. Click, type, log in, open devtools: it is a real screen, not a screenshot.

Useful for: manual testing and QA in a clean disposable browser, poking at sites that block headless automation, a scratch browser for tasks you don't want touching your own machine, browsing from a proxy IP in another country, or showing someone a running session live.

### How do I open a session?

1. Run the Actor (optionally set `startUrl` to open a specific page).
2. Once it is running in **Standby** mode, open its Standby URL in your own browser.
3. You land on the noVNC client — click **Connect** and you are looking at the live desktop. Use your mouse and keyboard as normal.

The session lives as long as the Standby run does. It shuts itself down after about five minutes with no traffic, and in any case when the run hits its timeout (one hour by default — raise it in the run options if you need longer). You can also stop the run from the Apify console at any time.

### What can I configure?

| Field | What it does | Default |
|---|---|---|
| `startUrl` | Page Firefox opens with on launch | `about:blank` |
| `vncPassword` | Password required to view and control the session | none (open access) |
| `screenWidth` / `screenHeight` | Resolution of the virtual screen, in pixels | `1360` x `768` |
| `proxyConfiguration` | Route Firefox through Apify Proxy (optionally by group and country) or your own proxy URL | none (direct connection) |

**Set `vncPassword`** unless the run is short-lived and private — without one, anyone who has the Standby URL can drive the browser. Note that it is a plain input field, not an Apify **Secret** input: the container reads its input with a plain API call at start-up and cannot decrypt Apify's secret-input encryption. Treat it as a short-lived session password, not a credential you reuse.

The input is read once, when the container starts. Changing it affects the next run, not one that is already warm.

### What is actually running inside?

| Component | What it is there for |
|---|---|
| **Debian 12 (bookworm)** | Base image, slim variant |
| **Firefox ESR** | The browser itself — a normal headful build, from Debian's own package |
| **Xvfb** | Virtual X11 display (`:99`, 24-bit colour) at the resolution you asked for — a screen with no physical monitor behind it |
| **fluxbox** | Minimal window manager, so Firefox has a title bar, right-click desktop menu and real windows |
| **x11vnc** | Exports that X display as a VNC server, in shared mode |
| **noVNC + websockify** | Translate VNC into something a plain browser tab can render, which is why you need nothing installed locally |
| **FoxyProxy** | Signed extension, pre-installed and pre-configured from your `proxyConfiguration` — it is what lets Firefox use an authenticated proxy without a password prompt |
| **dbus-x11, fonts-liberation** | Session bus and a base set of fonts, so pages render with sane typefaces |

Based on: https://www.trickster.dev/post/running-gui-apps-within-docker-containers/

#### What do these terms mean?

- **Headful vs headless** — a headless browser has no screen and is driven only by code. This one is headful: it draws to a real (virtual) display, so the page sees a window, a size, fonts and a cursor, and you interact with it by hand.
- **noVNC** — a VNC client written in JavaScript that runs inside a web page. Your tab talks WebSocket to `websockify`, which talks VNC to `x11vnc`. Nothing to install on your side.
- **Xvfb** — the X server that keeps a framebuffer in memory instead of sending it to a monitor. It is the "screen" Firefox believes it has.
- **Standby mode** — an Apify run that stays warm and answers HTTP requests instead of running once and exiting. It is what makes "open a link, get a live desktop" possible; a normal Actor run would have nothing to open.

### How much does it cost?

The Actor charge is a single flat fee, billed once per run when the container starts (see the **Pricing** tab) — it does not grow with how long you stay connected. On top of that you pay Apify platform usage for the time the run is up, which is the part worth watching: this is a desktop plus a browser, so it is provisioned with 1 GB of RAM in Standby mode. The five-minute idle shutdown and the run timeout are your safety net; stopping the run when you are done is the cheapest habit.

### FAQ

**Do I need to install anything?** No. Any modern browser can open the noVNC client — there is no VNC client, extension, agent or SSH key to set up. It works from a locked-down machine where you cannot install software.

**Is this a scraper?** No. It is a browser you operate by hand. There is no dataset output, no crawl input and no result rows; the "output" is the live session. Use it when you want to *look* at something yourself rather than extract it in bulk.

**Can I drive it with Playwright, Selenium or CDP?** Not over the network. The Actor exposes only the noVNC web endpoint — no remote-debugging port, no WebDriver, no CDP socket. It is built for hands-on use.

**Does anything persist between runs?** No. Every run starts a fresh container and builds a new Firefox profile, so cookies, logins, history, bookmarks and anything you download are gone when the run stops. Nothing is copied to a key-value store. Treat it as a disposable machine — that is the point — and if you need a file out of it, upload it somewhere from inside the session before you stop the run.

**Is my session private?** Standby runs for this Actor are single-tenant, so you get your own container rather than sharing one with other users of the Actor. Access control is the `vncPassword`: with no password, the Standby URL alone is enough for anyone who has it.

**Can two people watch the same session?** Yes. x11vnc runs in shared mode and Standby allows up to four concurrent requests per run, so a couple of viewers can connect to the same desktop at once and see the same cursor. Everyone connected can also control it.

**How do I browse from a different country?** Set `proxyConfiguration` to Apify Proxy and pick a country (or a proxy group); the Actor turns that into a proxy URL and pre-seeds FoxyProxy with it, credentials included. A custom proxy works too — `http`, `https`, `socks4` and `socks5` URLs are all recognised. Only the **first** URL in `proxyUrls` is used; the Actor does not rotate between them, because a hand-driven session wants one stable IP.

**Which apps besides Firefox are available?** Only Firefox and the fluxbox desktop are installed. There is no terminal emulator, file manager or second browser in the image.

**What if the screen is the wrong size?** Set `screenWidth` and `screenHeight` before the run. The virtual display is created at start-up and is not resized when you resize your browser window, so pick the resolution you want up front.

### Did you find this useful?

Rate this actor on Apify! Your feedback helps other users find it and helps us keep improving it.

# Actor input Schema

## `startUrl` (type: `string`):

URL Firefox opens on launch.

## `vncPassword` (type: `string`):

Optional password to protect the noVNC session. Leave empty for no auth (fine for short-lived sandbox runs only). Not stored as a Secret input: this actor reads its input via a plain API call at container start, which can't decrypt Apify's Secret input encryption.

## `screenWidth` (type: `integer`):

Width of the virtual display in pixels.

## `screenHeight` (type: `integer`):

Height of the virtual display in pixels.

## `proxyConfiguration` (type: `object`):

Route Firefox's traffic through Apify Proxy or a custom proxy server.

## Actor input object example

```json
{
  "startUrl": "about:blank",
  "screenWidth": 1360,
  "screenHeight": 768
}
```

# Actor output Schema

## `server` (type: `string`):

This Actor runs as a server rather than producing dataset rows. Start it in Standby mode and call this URL; the run's log records each request.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("rl1987/firefox-sandbox").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("rl1987/firefox-sandbox").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call rl1987/firefox-sandbox --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rl1987/firefox-sandbox"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/biGKbjdPbaofGREuM/builds/RbOKYIz4AFgzwS14B/openapi.json