Browser Context (upcoming)

Available in version 1.1.72 (not yet live).

Launch, quit, manage, and inspect the browser context and pages your TaskBot uses.

// @zw-run-locally

// Quick start (abridged)
await zw.browserContext.launch({
  launchConfig: {
    launchOptions: { headless: true },
  },
  /* More options available */
});
await zw.log("Context info", await zw.browserContext.getContextInfo());
await zw.browserContext.quit();

---

1. Core Concepts

Launching the browser context

Launch with zw.browserContext.launch() (ZeroWork-managed). This ensures:

• No-code blocks use the same context.

• Lifecycle is managed for you. To opt out of auto-quit, pass runConfig.keepAlive: true.

• (Re)launches reapply your launch arguments.

Note: If you need a custom launch flow or a self-managed context, see Advanced: Custom and self-managed contexts below.

---

Active page

A TaskBot has one active page at a time. No-code web-interaction blocks act on the active page. If you create a page in code and want no-code blocks to use it, set it with zw.browserContext.setActivePage(page).

---

Context (re)launch

A TaskBot automatically (re)launches a context in these cases:

• Open Link building block — launches one if none exists, otherwise reuses.

• Write JS set to run in the browser — launches one if none exists, otherwise reuses.

• A call to zw.browserContext.launch() — launches one and, depending on policy.makeMain, either replaces the existing context or creates a parallel one.

• Launch Browser building block — launches one and replaces the existing context.

• Recovery after staleness or a crash.

• Performance optimizations in long-running TaskBots.

💡 Common gotcha: Closing the last tab (e.g., with Switch or Close Tab) ends the context. The next Open Link block creates a fresh context from defaults.

Avoid surprises (e.g., “I launched a headless browser and it suddenly became headful mid-run”) with these best practices:

• Use zw.browserContext.launch() to launch. Don't use custom context launch flows like playwright.chromium.launch(). (If you need a custom launch flow, you can pass contextProvider.)

• Add cookies, scripts, and permissions via zw.browserContext.launch() or zw.browserContext.setDefaults() so that they reapply on (re)launches. Don't use ad hoc calls like context.addCookies().

---

Sticky mode (sticky profiles)

Sticky profiles follow special rules.

• One browser instance per profile. Same stickyProfileId ⇒ the same live browser instance across TaskBots (multiple isolated tabs).

• Later launches attach to the live browser instance and ignore conflicting browser-level args (e.g., headless). Other arguments like cookies, scripts and onContextReady still apply on attach (deduplicated).

• Quitting from one run closes that run’s tabs, but if other TaskBots are still using the browser instance it remains running and only quits when the last user leaves.

---

Lifecycle

Contexts are closed and cleared automatically.

• When a run ends, the context and browser quit unless runConfig.keepAlive is true or a shared sticky profile is still in use by other TaskBots.

• If runConfig.keepAlive is true but there are no open or eligible tabs, the context and browser still quit.

• If the browser stays open because of runConfig.keepAlive, the Desktop Agent cleans up when it detects manual closure (for example, when you close the window by clicking X). The listener also stays active after a TaskBot run, so cleanup is guaranteed even when no TaskBot is running.

⚠️ Caution: headless: true + keepAlive: true can leave an invisible instance consuming resources or, if mode: "sticky", blocking a sticky profile. The UI blocks this combination, but the API allows it—use with care.

---

Advanced: Custom or self-managed contexts

• Custom launch flow Provide a callback via contextProvider in zw.browserContext.launch() when you need options the standard zw API doesn’t cover (e.g., launching with Firefox). See examples here.

• Self-managed context Pass policy.makeMain: false in zw.browserContext.launch() to opt out of lifecycle and relaunch policy. No-code blocks keep using the main context. To rejoin the managed flow later, use zw.browserContext.adoptContext(). See examples here.

---

2. Launch the Browser — launch()

At a Glance

• async await zw.browserContext.launch(args: CustomLaunchArgs) → launches a new browser context and returns it.

Launch Arguments — CustomLaunchArgs

// Type reference — not runnable in Write JS
type CustomLaunchArgs = {
  launchConfig?: {
    mode?: "incognito" | "sticky"; // default: "incognito"
    stickyProfileId?: number;      // used only when mode="sticky" (ignored when mode="incognito")
    maximize?: boolean;            // default: true
    bypassDetection?: boolean;     // default: false
    cookies?: Array<CookieObject> | Array<Array<CookieObject>>;
    scripts?: Array<{ path: string } | { content: string }>;
    launchOptions?: LaunchOptions;  // headless, proxy, args, executablePath, etc.
    contextOptions?: ContextOptions;// viewport, permissions, userAgent, extraHTTPHeaders, etc.
    onContextReady?: (ctx: BrowserContext) => void | Promise<void>;
    contextProvider?: () => Promise<BrowserContext> | BrowserContext; // advanced: callback that returns a custom-launched context
  },
  runConfig?: {
    keepAlive?: boolean;            // default: false
    bringToFront?: boolean;         // default: true
  },
  policy?: {
    makeMain?: boolean;             // default: true
    inheritDefaults?: boolean;      // default: true
    setAsDefaults?: boolean;        // default: true if makeMain=true, else false
  },
};

Defaults used when you pass no arguments

All options are optional. If you call zw.browserContext.launch() with no arguments, it inherits the Browser Launch Settings configured for this TaskBot or any values previously set via zw.browserContext.setDefaults(). If you set policy.inheritDefaults: false, any option you don’t specify falls back to the built-in baseline defaults (the default: comments in the type definitions).

Note how mode affects the default baseline when policy.inheritDefaults: true:

• If you don’t pass mode, mode and its corresponding settings are inherited from the current defaults.

• If you pass mode: "sticky", defaults are taken from the sticky profile settings for the stickyProfileId you provide.

• If the current defaults use mode: "sticky" but you pass mode: "incognito", ZeroWork switches to the built-in baseline defaults and ignores the current defaults.

// @zw-run-locally

// ✅ Works: launch without passing any arguments
await zw.browserContext.launch();

---

Mode — launchConfig.mode and launchConfig.stickyProfileId

• mode (default: "incognito")

  Selects how ZeroWork launches and manages the browser context.

  • "incognito": Launches an isolated browser session.

  • "sticky": Launches in a sticky browser profile. Multiple TaskBots with the same stickyProfileId share the same browser instance in parallel tabs (see Sticky Profiles further below).

• stickyProfileId Selects which sticky profile to use (only relevant in sticky mode). Ignored when mode: "incognito".

---

Maximize Flag — launchConfig.maximize

• maximize (default: true) Maximizes the window. Ignored in headless mode (headless must use an explicit launchConfig.contextOptions.viewport, see Context Options further below).

---

Bypass Detection Flag — launchConfig.bypassDetection

• bypassDetection (default: false) Hardens bot detection bypass measures and keeps TaskBots indistinguishable from human users to Cloudflare and similar anti-bot systems. (Called previously powerMode in beta versions.)

  • ℹ️ Trade-offs: In bypassDetection mode, some launch and context options are unavailable (see Launch Options and Context Options further below) and file uploads larger than ~50 MB are blocked (downloads are unaffected).

---

Cookies — launchConfig.cookies

Provide cookies up front so they are reapplied on every context (re)launch. Each cookie must include at least name, value, and domain (and path, where relevant).

You can either provide the cookie array or, if you have cookies copied from multiple websites, an array of cookie arrays.

💡 Tip! Avoid adding cookies in code later via context.addCookies() — those won’t automatically reapply on context relaunch.

Example

// @zw-run-locally
await zw.browserContext.launch({
  launchConfig: {
    cookies: [ /** cookie array copied from a website **/ ],
  }
});

// Multiple cookies
await zw.browserContext.launch({
  launchConfig: {
    cookies: [
      [ /** cookie array for website 1 **/ ],
      [ /** cookie array for website 2 **/ ],
      [ /** cookie array for website 3 **/ ],
    ]
  }
});

---

Scripts — launchConfig.scripts

Scripts are injected before any page loads and reinjected on context (re)launch. Each script item is either { path } or { content } (when using path, provide an absolute path).

💡 Tip! Avoid adding scripts in code later via context.addInitScript() — those won’t automatically reapply on context relaunch.

Example

// @zw-run-locally
await zw.browserContext.launch({
  launchConfig: {
    scripts: [
      { content: `window._usedByTaskBot = ${(await zw.getTaskbotInfo()).id};` },
      { path: "/Users/me/scripts/guard.js" },
    ]
  }
});

---

Launch Options — launchConfig.launchOptions

// Type reference — not runnable in Write JS
type LaunchOptions = {
  args?: string[];           // Chrome/Chromium flags; use only for advanced use cases
  executablePath?: string;   // Chromium-based browser path; defaults to Chrome
  headless?: boolean;        // default: false
  proxy?: {
    server: string;          // "host:port" or "socks5://host:port"
    bypass?: string;         // comma-separated domains
    username?: string;
    password?: string;
  };
  // When launchConfig.bypassDetection is false, more options are available (e.g., channel).
};

• args Use with care: custom flags can break bot detection bypass measures. Note: --user-data-dir and --profile-directory are reserved. When bypassDetection is true, --remote-debugging-port is also reserved. If you pass a reserved flag (for example --user-data-dir), that flag is ignored.

• executablePath By default, your Chrome path is auto-detected and used. You can override it with any Chromium-based browser (e.g., Chrome, Brave, Vivaldi, Chromium). You can find the executable path by opening chrome://version in your browser. Note: Some Chromium forks (e.g., Opera) diverge too much and may not work.

• headless (default: false) Runs in the background and uses fewer resources.

• proxy For SOCKS5, prefix with socks5://. SOCKS5 auth isn’t supported — username and password apply to HTTP proxies only.

• More options when bypassDetection is disabled When launchConfig.bypassDetection is false, Playwright’s BrowserType.launch options are available. For the full list, see launch → Arguments here.

Example

// @zw-run-locally
await zw.browserContext.launch({
  launchConfig: {
    launchOptions: {
      headless: true,
      proxy: {
        server: "123.45.67.89:3128",
        username: "username",
        password: await zw.deviceStorage.get("proxy_password"),
      },
    },
  },
});

---

Context Options — launchConfig.contextOptions

// Type reference — not runnable in Write JS
type ContextOptions = {
  permissions?: string[];    // will include "clipboard-read" and "clipboard-write" by default
  userAgent?: string;        // dangerous! Changing can harm anti-detection
  viewport?: { width: number; height: number } | null;
  extraHTTPHeaders?: Object<string, string>
  // When launchConfig.bypassDetection is false, more options are available (e.g., recordVideo).
};

• permissions ZeroWork always grants "clipboard-read" and "clipboard-write" so that the Save From Clipboard building block works.

  • ⚠️ Avoid adding permissions in code later via context.grantPermissions() — those won’t automatically reapply on context relaunch.

• userAgent Unless you know exactly what you’re doing, prefer not to change it. If you change userAgent, anti-detection may no longer be fully guaranteed.

• viewport (default: { width: 1440, height: 900 }) Takes effect when maximize is disabled or when headless is enabled.

• extraHTTPHeaders Discouraged, because it can break bot detection bypass measures. Use with care.

• More options when bypassDetection is disabled When launchConfig.bypassDetection is disabled, Playwright’s Browser.newContext options are available. For the full list, see newContext → Arguments here.

  • ⚠️ Warning! Using Playwright API to set options like geolocation, extraHTTPHeaders, etc. can harm the built-in bot detection bypass measures.

Examples

Headless with explicit viewport

// @zw-run-locally
await zw.browserContext.launch({
  launchConfig: {
    launchOptions: { headless: true },
    contextOptions: {
      viewport: { width: 1000, height: 600 }
    },
  }
});

Record a video

// @zw-run-locally
await zw.browserContext.launch({
  launchConfig: {
    bypassDetection: false,  // disable bypassDetection to unlock recordVideo
    contextOptions: {
      recordVideo: {
        dir: "/Users/me/zw-runs/videos",
        size: { width: 800, height: 450 },
      },
    },
  }
});

---

Callback when Ready — launchConfig.onContextReady

Runs whenever the context is (re)launched.

Example

// @zw-run-locally
import * as crypto from "crypto";

await zw.browserContext.launch({
  launchConfig: {
    onContextReady: async (context) => {
      // Example 1: Expose a function from an imported package
      await context.exposeFunction(
        "sha256",
        (text) => crypto.createHash("sha256").update(text).digest("hex")
      );
  
      // Example 2: Save bandwidth by blocking images
      await context.route('**/*.{png,jpg,jpeg}', r => r.abort());
    },
  }
});

---

Context Provider — launchConfig.contextProvider — Advanced

Provide a custom launch callback. Use it when you need a custom-launched context but still want no-code blocks to use it and want to benefit from lifecycle management and relaunch policy.

Use cases

• You must use a browser the ZeroWork launch API doesn’t support out of the box (for example, Firefox instead of Chromium).

• You need a 100% pristine context without ZeroWork’s built-in anti-detection measures or defaults.

Example

Launching Firefox

// @zw-run-locally
import "@playwright/[email protected]"; // ensures Playwright Firefox browser gets installed
import { firefox } from "playwright";

const launchFirefoxContext = async () => {
  const firefoxBrowser = await firefox.launch();
  const context = await firefoxBrowser.newContext();

  return context;
};

await zw.browserContext.launch({
  launchConfig: {
    contextProvider: launchFirefoxContext,
    cookies: [ /** cookies **/ ],
    scripts: [ /** scripts **/ ],
    onContextReady: () => zw.log("My Firefox context is ready."),
  }
});

await zw.browserContext.createPage({ url: "https://wikipedia.org" });
await zw.delay({ min: 5_000 });

Because you supply the context, you control launchOptions (headless, proxy, etc.), contextOptions (viewport, permissions, etc.), window size, and any anti-detection choices. ZeroWork adopts your context, applies cookies and scripts, then runs onContextReady. Use this only if you need full control over browser creation and understand the trade-offs.

These arguments are ignored when contextProvider is set

• launchConfig.launchOptions

• launchConfig.contextOptions

• launchConfig.maximize, launchConfig.bypassDetection

The rest of the arguments apply — including their corresponding defaults if policy.inheritDefaults is true or left undefined (default is true).

⚠️ Exception: Here, mode is always treated as "incognito". If you pass mode: "sticky", ZeroWork throws an error because sticky mode isn’t supported when contextProvider is used. Naturally, you fully control what happens inside contextProvider, so you can launch with your own persistent browser profile there (e.g., with Playwright’s launchPersistentContext()). ZeroWork just won’t treat it as sticky mode, meaning there’s no built-in browser instance sharing and no profile locking.

---

Run Config — runConfig

• keepAlive (default: false) Keeps the browser open after the run ends.

  • 💡 keepAlive: true is ignored if, at run end, no pages remain. The context then closes. Tabs on about:blank or ZeroWork launch pages don’t count unless they are tied to Write JS in-browser code execution.

  • ℹ️ In sticky profiles, keepAlive applies only to this run’s tabs. If true, your tabs remain open; if false, your tabs close. The browser instance itself stays running as long as another TaskBot in the same profile is using it. It quits only when the last user leaves and no kept-alive tabs remain.

    • ⚠️ With sticky profiles, prefer leaving keepAlive false. After a long device sleep, the connection can drop while the browser stays open, blocking the profile until you restart the Desktop Agent or quit that browser. Only one browser instance can use a profile at a time.

• bringToFront (default: true) Brings newly opened tabs to the front (applies to no-code blocks that open tabs).

---

Policy Options — policy

• inheritDefaults (default: true) Inherits values from Browser Launch Settings or any values previously saved via zw.browserContext.setDefaults() for options you don’t specify. Note that if you pass launchConfig.mode: "sticky", the inherited defaults come from the sticky profile’s settings (based on stickyProfileId). Likewise, if the current defaults’ mode is set to "sticky" but you explicitly pass mode: "incognito", ZeroWork falls back to the built-in baseline defaults and ignores the current defaults. Example: If Browser Launch Settings have Run in background on and you don’t set headless in launchConfig.launchOptions, headless will be inherited as true.

• makeMain (default: true) — advanced If true, the launched context becomes the main context. The previous main context is closed (unless its runConfig.keepAlive setting is true). If you set it to false, you partially lose automatic lifecycle, retries, and no-code blocks will keep using the old context.

  • ⚠️ Leave makeMain at true unless you’re deliberately running a self-managed context for an advanced use case. If you do, see Adopt Self-Managed Contexts for more details further below.

  • 💡makeMain: false is ignored if you launch a context with a sticky profile that is already launched and has already been made main elsewhere. This is because launches of the same sticky browser profile all share the same browser instance, see Sticky Profiles for more details further below.

• setAsDefaults (default: true if makeMain is true, otherwise false) — advanced Sets these options for future launches as well as automatic relaunches (e.g., after a staleness or crash recovery) for the rest of the TaskBot run.

  • ⚠️ If you set setAsDefaults to false, a later relaunch may revert to older defaults. Likewise, if you set setAsDefaults to true while makeMain is false, the main context may relaunch with unexpected, unrelated settings. Prefer keeping the default.

---

3. Defaults — setDefaults(), getDefaults(), resetDefaults()

Defaults are the settings a TaskBot uses when launching or relaunching contexts. You can ensure that any subsequent launch or relaunch uses the settings you want by setting defaults.

See Core Concepts → Context (re)launch for a list of cases when a browser context is (re)launched.

At a Glance

• async await zw.browserContext.getDefaults() → returns CustomLaunchArgs.

• async await zw.browserContext.setDefaults(args: CustomLaunchArgs) → updates the TaskBot-level default launch settings for the current run.

• async await zw.browserContext.resetDefaults() → resets the TaskBot-level default launch settings to what’s defined in Browser Launch Settings.

Notes

• zw.browserContext.getDefaults() excludes policy, which is only meaningful when launching or setting defaults.

• In setDefaults(), only policy.inheritDefaults is accepted (makeMain and setAsDefaults are ignored — they have no effect when setting defaults).

Examples

Set all subsequent (re)launches to headless

// @zw-run-locally
await zw.browserContext.setDefaults({
  launchConfig: {
    launchOptions: { headless: true },
  }
});

await zw.browserContext.launch(); // now guaranteed to launch headless

Discover a sticky profile’s ID

const defaults = await zw.browserContext.getDefaults();
const stickyProfileId = defaults?.launchConfig?.mode === "sticky"
  ? defaults.launchConfig.stickyProfileId
  : null;

await zw.log("Sticky profile ID:", stickyProfileId);

---

4. Context — getContextInfo(), getContext()

At a Glance

• zw.browserContext.getContext() → returns the current main browser context.

• async/sync* await zw.browserContext.getContextInfo() → returns:

  {
    id: string,
    contextProps: {
      mode: "sticky" | "incognito",
      stickyProfileId?: number, // when mode="sticky"
      maximize?: boolean,
      headless?: boolean,
      bypassDetection?: boolean,
      proxy?: string,           // proxy server, example: '102.242.95.95:6407'
      foreignContext?: boolean, // advanced: true if launched with contextProvider
    },
    usedInTaskbots: number[],   // TaskBots currently using this context (can be multiple when mode="sticky")
    runConfig: {
      keepAlive?: boolean,
      bringToFront?: boolean,
    },
  } | null

*async in browser, sync locally (see Local vs. Browser Execution).

Working with the returned context

You can call any Playwright BrowserContext API. For the full list of available methods, properties and events, see here.

⚠️ Avoid adding cookies, scripts, and permissions via the context API (e.g., context.addCookies()). Instead, pass them to zw.browserContext.launch() or zw.browserContext.setDefaults() (e.g., zw.browserContext.launch({ launchConfig: { cookies: [] } })) so that they reapply on relaunch.

⚠️ Avoid changing user agent, timezone, locale, or geolocation (e.g., context.setGeolocation()), as this can harm the built-in anti-detection measures.

Examples

Add a listener

// @zw-run-locally
const context = zw.browserContext.getContext();
context.on("close", async () => {
  await zw.log("Context is being closed.");
});

Clear cookies

// @zw-run-locally
const context = zw.browserContext.getContext();
await context.clearCookies();

Relaunch non-headless if the current context is headless

// @zw-run-locally

const contextInfo = await zw.browserContext.getContextInfo();

if (contextInfo?.contextProps?.headless) {
  // Relaunch because a headful browser is required
  await zw.browserContext.quit();
  await zw.browserContext.launch({
    launchConfig: {
      launchOptions: { headless: false },
    }
  });
  await zw.log("Browser is relaunched.");
  
  const updatedInfo = await zw.browserContext.getContextInfo();
  await zw.log("Confirm headless is now false", updatedInfo.contextProps.headless);
}

---

5. Sticky Browser Profiles — clearProfile(), cloneProfile(), listProfiles()

Sticky profiles let multiple TaskBots share one browser session (same cookies/storage/fingerprint) via a persistent, shared user data directory.

At a Glance

• async await zw.browserContext.clearProfile({ stickyProfileId: number }) → clears the profile, or refuses to clear if the profile is in use.

• async await zw.browserContext.cloneProfile({ cloneTo: { stickyProfileId: number }, cloneFrom: { profilePath: string } }) → clones the profile, or refuses to clone if the target profile is in use. You can find the profile path by opening chrome://version in your browser and copying the Profile Path value.

• async await zw.browserContext.listProfiles() → lists available profiles.

Behavior

• Parallel TaskBots, one instance: One shared browser instance (with multiple isolated tabs) per stickyProfileId.

• In-use lock: If a profile is in use, both clearProfile and cloneProfile will fail to avoid breaking active runs.

• Create and discover: You can create sticky profiles in Browser Launch Settings at creator.zerowork.io. You can’t create them via the API, but you can:

  • Create one in the UI (Browser Launch Settings).

  • Click Save to create the profile. Then open the profile again — the Profile ID appears at the bottom left. Copy it from there, or run zw.browserContext.listProfiles() to discover it.

  • Use that profile ID as stickyProfileId programmatically.

• contextProvider and sticky mode: contextProvider isn’t supported in sticky mode. If mode is "sticky" and contextProvider is provided, ZeroWork throws an error.

Shared Browser Side Effects

• Non-deterministic tab order across independent TaskBots. If you need to switch programmatically, match by URL and/or TaskBot ID. Example

  // @zw-run-locally
  const TASKBOT_ID = 1243;
  
  const pagesForThisBot = zw.browserContext
      .listPages()
      .filter(p => p.usedBy === TASKBOT_ID);

• Attach semantics — when a browser instance is already live for that profile ID and a launch event attaches to it, browser-level arguments are ignored and others are applied. By default, applied items affect the whole context, so other TaskBots sharing the instance will see them (except keepAlive and bringToFront, which apply to this run’s tabs only). Ignored on attach:

  • launchConfig.launchOptions

  • launchConfig.contextOptions

  • launchConfig.bypassDetection, launchConfig.maximize

  Applied:

  • runConfig — applies to this run's tabs only.

  • launchConfig.scripts — scripts that already ran are ignored; any new scripts are applied (context-wide).

  • launchConfig.cookies — duplicate cookies by the same name + domain + path are ignored; any new cookies are applied (context-wide).

    • ⚠️ Be careful not to pass conflicting cookies or two distinct cookies with the same name/domain/path (duplicates will be ignored).

  • launchConfig.onContextReady — runs on every attach (gate it if you want it to run only on true (re)launches). Gate example:

    // @zw-run-locally
    await zw.browserContext.launch({
      launchConfig: {
        mode: "sticky",
        stickyProfileId: 6567,
        onContextReady: async (context) => {
          // Runs on every attach; gate if you only want true (re)launches
          if (context._onContextReadyRan === true) {
            await zw.log("Attach detected — skipping onContextReady.");
            return;
          }
          await zw.log("Running onContextReady on a true (re)launch only.");
          context._onContextReadyRan = true;
        },
      },
    });

Anti-patterns

• keepAlive caution. We don’t recommend setting runConfig.keepAlive to true in zw.browserContext.launch() or zw.browserContext.setDefaults() when using sticky profiles. After a long device sleep, the connection can drop while the browser stays open, blocking the profile until you restart the Desktop Agent or quit that browser. Only one browser instance can use a profile at a time. Prefer leaving runConfig.keepAlive: false for sticky profiles.

---

6. Quit Browser — quit()

At a Glance

• async await zw.browserContext.quit(opts?: { forceQuit?: boolean }) → closes the current context and the browser instance.

Behavior

• Closes the current run’s pages and attempts to close the browser/context.

• Since zw.browserContext.quit() is called explicitly, the keepAlive setting is ignored.

• In sticky profiles:

  • If other TaskBots are still using the same instance, pages from this run close, but the browser instance does not quit.

  • If no other TaskBots are using the instance, the browser quits fully.

  • forceQuit: true forces termination even if mode is "sticky" and browser is actively shared. Use with care.

💡Contexts are automatically managed and closed when needed. See Core Concepts → Lifecycle. You only need to call zw.browserContext.quit() if it's part of your logic. Otherwise, lifecycle management is handled out of the box.

---

7. Active Page & Pages — setActivePage(), getActivePage(), isActivePage(), createPage(), listPages()

At a Glance

• async await zw.browserContext.setActivePage(page: Page, options?: { forceContextMismatch?: boolean }) → makes a Page the “active page” used by no-code building blocks that do web interactions.

• zw.browserContext.getActivePage() → returns Page | null, i.e. the page (if any) currently used by the TaskBot and its no-code building blocks.

• zw.browserContext.isActivePage(page: Page) → returns boolean

• async await zw.browserContext.createPage({ url?: string, context?: BrowserContext }) → creates a new page and returns Page

• zw.browserContext.listPages() → returns:

  Array<{
    page: Page,
    url: string,
    isActive: boolean,
    contextId: string,
    usedBy: number, // TaskBot ID
  }>

What’s an active page?

The active page is the page that no-code web-interaction blocks act on. There can be only one active page at a time. You can open other pages in code, but unless you set one as active, no-code blocks won’t use it.

Example

// @zw-run-locally
const page = await zw.browserContext.createPage({ url: "https://wikipedia.org" });
await zw.browserContext.setActivePage(page);

Notes & caveats

createPage — create in custom context — advanced

By default, pages are created in the current main context. If you need to create a page in a self-managed, non-main context, you can pass it in context, and the page will be created there instead.

const page = await zw.browserContext.createPage({ context: myCustomContext });

Context mismatch & forceContextMismatch

If the page belongs to a different browser context than the current main context, an error is thrown similar to:

The page you provided belongs to a different browser context than the current main context. If you must use a custom launch flow, provide contextProvider in zw.browserContext.launch(). If you must use a self-managed context, use zw.browserContext.adoptContext() to adopt it before calling zw.browserContext.setActivePage(). While not recommended, you can also set forceContextMismatch to true.

• forceContextMismatch (default: false) — advanced

  • Consider it an escape hatch. Setting to true is not recommended.

  • If set to true, the page is made active even if it belongs to a foreign context. No-code blocks will now operate on the active page, but inconsistencies can arise when Switch or Close Tabs is used, when a context relaunches, or when you use zw.browserContext.getContext().

  • If you must launch a custom context, explore contextProvider in zw.browserContext.launch() first. For more advanced use cases and self-managed contexts, explore zw.browserContext.adoptContext().

Two ways to hit a mismatch

1. Launching a second context with makeMain: false and creating a page there.

2. Creating a context entirely outside zw.browserContext.launch() (e.g., using the Playwright BrowserType API).

Bad (illustrative) pattern

// 🚫 Bad (illustrative) pattern

// Launch main context
const context1 = await zw.browserContext.launch();

// Launch a second independent context
const context2 = await zw.browserContext.launch({
  // 🚫 Bad: makeMain is false → launched a loose, non-managed context
  policy: { makeMain: false } 
});
const page = await context2.newPage();

// This will throw unless forceContextMismatch is set to true (not recommended)
await zw.browserContext.setActivePage(page);

---

8. Adopt Self-Managed Contexts (Advanced)

For advanced use cases, you can create additional (non-main), self-managed contexts via zw.browserContext.launch() and then let ZeroWork adopt one of them as the active, managed context.

At a Glance

• async await zw.browserContext.adoptContext(context: BrowserContext) → adopts a non-main context launched by zw.browserContext.launch() (with policy.makeMain: false).

⚠️ Contexts created directly via the Playwright BrowserType API are not accepted. If you need a custom launch flow, provide it via contextProvider in zw.browserContext.launch().

Example

Switching between two launched (non-main) contexts

// @zw-run-locally

// Launch two independent contexts (illustrative; only do this if you truly need it)
const LINKEDIN_ACCOUNT_A = [/* cookies */];
const PROXY_USA = { server: "socks5://..." };

const LINKEDIN_ACCOUNT_B = [/* cookies */];
const PROXY_ITALY = { server: "socks5://..." };

const launchArgsA = {
  launchConfig: {
    cookies: LINKEDIN_ACCOUNT_A,
    launchOptions: { proxy: PROXY_USA },
  },
  runConfig: { keepAlive: true },
  policy: { makeMain: false }, // create as non-main
};
const contextA = await zw.browserContext.launch(launchArgsA);
const pageA = await zw.browserContext.createPage({ context: contextA });

const launchArgsB = {
  launchConfig: {
    cookies: LINKEDIN_ACCOUNT_B,
    launchOptions: { proxy: PROXY_ITALY },
  },
  runConfig: { keepAlive: true },
  policy: { makeMain: false }, // create as non-main
};
const contextB = await zw.browserContext.launch(launchArgsB);
const pageB = await zw.browserContext.createPage({ context: contextB });

// Persist references across blocks and TaskBots (same Desktop Agent)
const globalState = zw.globalState.access();
globalState.contexts = {
  A: { context: contextA, page: pageA, defaults: launchArgsA },
  B: { context: contextB, page: pageB, defaults: launchArgsB },
};

const adoptSafely = async ({ context, page, defaults }) => {
  // Adopt the context into the managed flow
  await zw.browserContext.adoptContext(context);

  // Ensure continuity on relaunches
  await zw.browserContext.setDefaults(defaults);

  // Point no-code blocks to the right page
  await zw.browserContext.setActivePage(page);
};

// Persist helper so it can be called in other TaskBots/blocks
globalState.adoptSafely = adoptSafely;

// Later in another block or TaskBot: adopt and switch to A
await globalState.adoptSafely(globalState.contexts.A);

// Later in another block or TaskBot: adopt and switch to B
await globalState.adoptSafely(globalState.contexts.B);

---

Notes

• Largely unavailable in browser execution. The zw.browserContext.* API is available mostly for local code execution. Only inspection methods zw.browserContext.getContextInfo() and zw.browserContext.getDefaults() are supported in the browser.