> For the complete documentation index, see [llms.txt](https://docs.zerowork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zerowork.io/using-zerowork/using-building-blocks/launch-browser.md).

# Launch Browser

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FdMAbHIFSw53z5nLCHDEh%2Flaunch_browser_block.png?alt=media&amp;token=57d62cda-e288-4666-8ce3-ca85d2ecf879" alt=""><figcaption></figcaption></figure>

The **Launch Browser** block allows you to launch a browser for your TaskBot to use. Subsequent no-code web-interaction blocks (like Click Web Element, Save Web Element, etc) act on the browser context this block launches.

{% hint style="success" %}
This block is one of several ways to launch a browser. You can also launch with an [Open Link](/using-zerowork/using-building-blocks/open-link.md) block or programmatically via `zw.browserContext.launch()` in a [Write JS](/using-zerowork/using-building-blocks/write-javascript.md) block. For the latter, see [Browser Context](/using-zerowork/using-building-blocks/write-javascript/browser-context.md) for the full API.
{% endhint %}

#### How To Use It

This block works with no configuration.

You might not need to use this block. Every setting listed below defaults to **Use current defaults**, which inherits from your TaskBot's **Browser Launch Settings** or any values previously set via `zw.browserContext.setDefaults()` in a Write JS block.

This block lets you override individual settings as needed *during* a TaskBot's run without a Write JS block.

{% hint style="success" %}
These overridden settings become the new defaults for this TaskBot at runtime. To reset or undo, add another Launch Browser block that reverses the previous Launch Browser block's settings prior to subsequent blocks.
{% endhint %}

***

**Launch mode**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FwWSLUwRlaE02EOL7dLt2%2FZeroWork%20sticky%20mode.png?alt=media&amp;token=c8ae46da-f30a-4a26-95ea-aa34d35fa153" alt=""><figcaption></figcaption></figure>

Controls how the browser session is managed.

* **Use current defaults** inherits from your TaskBot's Browser Launch Settings.
* When unchecked, you can choose between:
  * **Incognito** an isolated browser session. No data persists between runs.
  * **Sticky** a persistent browser profile. Cookies, storage, and login state survive between runs. Select your **Sticky profile** from the list of available profiles. Select **Custom** to enter a variable, table reference, or expression that resolves to a sticky profile ID. (You can find the profile ID in the sticky profile dialog, in the bottom-left corner.)

{% hint style="success" %}
You can create new sticky profiles in **Browser Launch Settings** to make them available here.
{% endhint %}

***

**Run mode & window**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2F0rJ48v7gCiJ7Ah1BQffU%2Frun_mode_window.png?alt=media&amp;token=57bc4e98-19bc-48f6-b45b-d3ba3ffd35c6" alt=""><figcaption></figcaption></figure>

**Bypass bot detection**

When enabled, your TaskBot is no longer detectable as bot automation.

{% hint style="warning" %}
When Bypass bot detection is enabled, file uploads larger than approximately 50 MB are blocked. File downloads are unaffected.
{% endhint %}

**Run in background**

Runs the browser in the background with no visible window. Uses fewer resources.

{% hint style="success" %}
When running in background, the browser uses a fixed viewport. If you don't set a **Window size**, the default (1440 x 900) is used.
{% endhint %}

**Maximize**

Maximizes the browser window on launch. Ignored when running in background.

**Window size**

Sets the browser viewport dimensions. This setting only takes effect when **Maximize** is off or **Run in background** is on.

* **Use current defaults** inherits the current viewport size.
* When unchecked, you can set **Width** and **Height** in pixels.

***

**Cookies**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FXpVxS3GI66EoLxQ0pzAH%2Fcookies.png?alt=media&amp;token=f61584e8-4f77-4e37-896a-02aa97a1538a" alt=""><figcaption></figcaption></figure>

Provide cookies up front so they are reapplied on every context relaunch.

* **Use current defaults** inherits cookies from your Browser Launch Settings.
* When unchecked, paste cookie JSON into the text field. Each cookie should include at least `name`, `value`, and `domain`.
* Click **+ ADD COOKIE** to add cookies from additional websites. Click the trash icon to remove one.

{% hint style="success" %}
See [Cookies](/using-zerowork/general-run-schedule-share-webhooks/cookies.md) for how to export cookies from your browser and use them in ZeroWork.
{% endhint %}

{% hint style="info" %}
**Tip!** When using [sticky profiles](https://docs.zerowork.io/using-zerowork/using-building-blocks/pages/XWp5BZ8Q3rsexcTMwOM0#id-5.-sticky-browser-profiles-clearprofile-cloneprofile-listprofiles), prefer logging in manually on the first run instead of adding cookies. Cookies are a snapshot of a session and can expire or be invalidated. A sticky profile, in contrast, preserves and continues the browser session after you log in.
{% endhint %}

***

**Proxy**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FkQxPsBE9iynLG8I1uwhU%2Fproxies.png?alt=media&amp;token=5a2e6845-9045-4590-9d44-fdf05cb487e1" alt=""><figcaption></figcaption></figure>

Route browser traffic through a proxy server.

* **Use current defaults** inherits proxy settings from your Browser Launch Settings.
* When unchecked:
  * **Proxy server** `host:port` or `socks5://host:port` for SOCKS5 proxies.
  * **Username** HTTP proxy authentication. Not supported for SOCKS5.
  * **Password** HTTP proxy authentication. Not supported for SOCKS5.
  * **Bypass domains** comma-separated domains to bypass the proxy (for example, `example.com, google.com`)

{% hint style="success" %}
See [Proxies](/using-zerowork/general-run-schedule-share-webhooks/proxies.md) for more info on how to use proxies in ZeroWork.
{% endhint %}

{% hint style="info" %}
**Tip!** When using a proxy, also set the timezone to match the proxy's location. ZeroWork automatically detects the proxy's timezone when possible, but setting it explicitly avoids mismatches if the proxy location can't be determined.
{% endhint %}

***

**Timezone & Locale**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FiZaNcQJQwHCT4uGXi30U%2Ftimezone-locale.png?alt=media&amp;token=186d46cd-eb64-4e6d-a8d3-c5d07200cc18" alt=""><figcaption></figcaption></figure>

Controls the timezone and language the browser reports to websites.

* **Use current defaults** inherits from your Browser Launch Settings.
* When unchecked:

  * **Timezone** select an IANA timezone from the list (for example Europe/Berlin). Select Custom to enter a variable, table reference, or expression that resolves to one.

  > 💡**Tip!** Set the timezone only to match your proxy's location, or when the TaskBot runs on a remote machine such as a VPS.

  * **Locale** select a language tag from the list (for example en-US). Select Custom to enter a variable, table reference, or expression that resolves to one.

  > 💡**Tip!** Set the locale only when the TaskBot runs on a remote machine whose language differs from your accounts' language. Unlike the timezone, the locale should not follow the proxy — instead, it should reflect the language your accounts are normally used in.

{% hint style="success" %}
If the TaskBot runs on your own device without a proxy, leave both empty. Empty means the browser uses your device's timezone and language, which is what looks most natural to websites.
{% endhint %}

***

**Browser**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FEn1WsVylo1iLIKkNsFRv%2Fbrowser.png?alt=media&amp;token=2a72548c-d2ae-4a57-899b-20916d0b43ba" alt=""><figcaption></figcaption></figure>

Controls which browser executable to use at runtime.

* **Use current defaults** inherits from your Browser Launch Settings.
* When unchecked, you can choose between:
  * **Default Chrome browser** your installed Chrome is auto-detected and used.
  * **Custom browser** provide a **Browser path** to any Chromium-based browser (Chrome, Brave, Chromium, etc)

{% hint style="success" %}
Not sure where to find your machine's browser path? Open `chrome://version` or `brave://version` in your browser choice and copy the **Executable Path** value.
{% endhint %}

{% hint style="info" %}
If you provide a custom browser path, it must point to a Chromium-based browser (Chrome, Chromium, Brave, Vivaldi, etc.). To use a non-Chromium browser, such as Firefox, use the advanced `launchConfig.contextProvider` option in the [`zw.browserContext.*`](/using-zerowork/using-building-blocks/write-javascript/browser-context.md) API (see **Browser Context → Context Provider**).
{% endhint %}

***

**Launch Arguments**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FdYxMYM5R4ek8qR9HUz1C%2Flaunch_arguments.png?alt=media&amp;token=db938998-d6d2-4003-88bb-37ab98a28bca" alt=""><figcaption></figcaption></figure>

Custom browser executable command line arguments.

* **Use current defaults** inherits from your Browser Launch Settings.
* When unchecked, enter **Chrome command line arguments** as space-separated flags (for example "--mute-audio --disable-notifications")

{% hint style="warning" %}
Some arguments can interfere with ZeroWork's built-in bot detection bypass and may also prevent the browser from launching. Only add arguments if you know what they do. For a full list of command-line arguments, see [Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches)
{% endhint %}

***

**Scripts**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FQpt4AkDXmnZNn94eDgP4%2Fscripts.png?alt=media&amp;token=9e52f3d1-edae-4ab5-85a5-3b3d79c274e6" alt=""><figcaption></figcaption></figure>

Scripts are injected before any page loads and reinjected on context relaunch.

* **Use current defaults** inherits from your Browser Launch Settings.
* When unchecked, you can add one or more scripts. Each script can be one of:
  * **Path** an absolute file path to a `.js` file (e.g., `/Users/<username>/Documents/script.js`).
  * **Content** inline JavaScript code.
* Click **+ ADD SCRIPT** to add additional scripts. Click the trash icon to remove one.

{% hint style="warning" %}
If you're adding scripts to bypass bot detection, don't. Modern bot-detection systems can detect the spoofing itself, so pasted or AI-generated stealth scripts can make your browser easier to flag. Prefer enabling **Bypass bot detection** and letting ZeroWork handle this natively.
{% endhint %}

***

**Page visibility**

<figure><img src="https://3220183989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg9LcR8XM7TGOzOCDGsCS%2Fuploads%2FYbseTcq9TytL0a51DyJ9%2Fpage_visibility.png?alt=media&amp;token=cd373825-428c-4dda-bdf3-6d010d72c2e8" alt=""><figcaption></figcaption></figure>

**Stay on page after run**

When enabled, the browser stays open after the TaskBot run ends.

{% hint style="info" %}
When **Run in background** is enabled, **Stay on page after run** has no effect. The browser closes when the TaskBot run ends to avoid leaving an invisible browser instance consuming resources. If your use case requires this advanced combination, you can enable it programmatically via [`zw.browserContext.launch()`](/using-zerowork/using-building-blocks/write-javascript/browser-context.md).
{% endhint %}

{% hint style="warning" %}
When using [sticky profiles](https://docs.zerowork.io/using-zerowork/using-building-blocks/pages/XWp5BZ8Q3rsexcTMwOM0#id-5.-sticky-browser-profiles-clearprofile-cloneprofile-listprofiles), **Stay on page after run** is not recommended. After a long machine sleep, the connection may drop while the browser stays open, which can block the sticky profile until you restart the Desktop Agent or quit the browser.
{% endhint %}

***

#### Things To Know

* **This block always becomes the main browser context.** It replaces any existing browser context. If a [Write JS](/using-zerowork/using-building-blocks/write-javascript.md) block already launched a context, this block replaces it.
* **Settings become defaults for this run.** Whatever you configure in this block becomes the active defaults for the rest of the run until you change it.
* **There's one browser per sticky profile.** Multiple TaskBots with the same sticky profile ID share the same browser instance in parallel tabs. This block attaches to the existing instance if one is already running. When attaching, browser-level settings (Run in background, Bypass bot detection, Maximize, Window size, Browser, Launch arguments) are ignored as they would've already been set when the browser first launched. Cookies, Scripts, and Page visibility settings still apply.
* **Closing the last tab ends the context.** If a [Switch or Close Tab](/using-zerowork/using-building-blocks/switch-or-close-tab.md) block closes the last tab, the context ends. The next [Open Link](/using-zerowork/using-building-blocks/open-link.md) block creates a fresh context from the current defaults.

#### Block Behavior

* **When no browser exists** this block launches a new browser with the configured settings. No URL is opened initially; the browser starts on `about:blank`. Use an [Open Link](/using-zerowork/using-building-blocks/open-link.md) block after this to navigate to a URL.
* **When a browser already exists (from** [Open Link](/using-zerowork/using-building-blocks/open-link.md)**,** [Write JS](/using-zerowork/using-building-blocks/write-javascript.md)**, or a previous Launch Browser block)** this block closes the existing context and launches a new one.
* **When a sticky profile browser is already running from another TaskBot** this block attaches to the existing browser instance. Browser-level settings are ignored. Cookies, Scripts, and Page visibility settings still apply.