This guide expands the product concepts and workflows summarized in the canonical README. The desktop source, tests, packaging configuration, and release automation are maintained in this repository.
NextBrowser is an Electron, React, and TypeScript desktop console for macOS and Windows. It coordinates local AI agents and managed browser sessions in one observable desktop workspace.
| Layer | Operator control |
|---|---|
| Account | Browser-paired NextBrowser account and proxy-traffic access. |
| Profile | Browser identity, country selection, and proxy/fingerprint rotation. |
| Session | Start or stop the browser, open pages, select tabs, and inspect state. |
| Agent | Choose a local agent and control chat history, queues, edits, stops, and forks. |
| Workflow | Apply skills or custom scripts, run preflight, and schedule repeated work. |
| Observation | Watch Live View and use status, state, screenshots, and verification diagnostics. |
Choose Sign in to NextBrowser in the desktop app, continue in your browser, and approve the pairing request. After approval, the app configures its local browser-control credential; you do not need to paste an API key into the desktop UI.
Keep credentials out of prompts, chat messages, skills, custom scripts, screenshots, logs, and repository files.
A profile represents a browser identity and its associated state. Profiles let an operator separate browser contexts for different tasks, accounts, customers, regions, or test runs.
A profile may exist while its browser session is stopped. Selecting a profile does not by itself prove that its session is running, its expected tab is active, or its identity matches the requested country.
A session is the running browser context for a profile. The session must be running before an agent can work with its pages. Session diagnostics include status, open tabs, page state, screenshots, and identity verification.
New accounts are shown a 1 GiB free proxy allowance, but they are provisioned with a smaller starting limit — somewhere between 70 MiB and 170 MiB. When that starting limit is reached, proxy traffic pauses and Proxy usage explains how to unlock the rest: ask in the NextBrowser Discord. The remaining allowance is then released by hand, one 1 GiB grant at a time, up to a 3 GiB ceiling. Feedback, repository stars, and pull requests are what earn the larger grants.
Accounts created before this gate keep their existing allocation and are never paused by it.
Rotation requests a refreshed browser identity, optionally with a country. Verification should follow rotation when a workflow depends on geography or identity consistency.
Rotation is a recovery and isolation tool, not a promise that a site will accept a session. Sites apply their own policies and risk systems.
An agent is an installed local runtime that receives a task and can use the active browser context. Claude Code connects through its CLI. Codex connects through the executable bundled with the ChatGPT desktop app, so no separate Codex CLI installation is required. NextBrowser provides the visible work surface around that process:
- chat history and named conversations;
- queued prompts and run status;
- stop and edit controls;
- conversation forks;
- streamed output and activity updates.
The agent still needs to be installed, discoverable, and authenticated for its own service.
If the selected agent is missing, use the official Claude Code installation guide or download ChatGPT for desktop.
NextBrowser passes the selected profile name to the local agent as context. This is guidance, not technical containment: confirm the actual profile and running session in the sidebar and Live View.
A skill is a reusable instruction set for a domain or browser workflow. A custom script is a private reusable instruction set for work that is too specific to publish as a general skill.
Before dispatching one of these workflows, the documented preflight sequence can:
- confirm that the selected profile is running;
- start it when required;
- inspect open tabs;
- activate an existing matching tab or open the target page;
- wait for the page to be ready;
- send the prepared prompt to the selected agent.
Preflight establishes a starting context. It does not guarantee that the page remains unchanged or that the workflow succeeds.
A scheduled run stores a prompt, selected agent, time, weekday selection, and enabled state. It runs locally while the NextBrowser desktop app is open. Use schedules for recurring browser tasks that have clear authorization and a review path; they are not a service-level guarantee.
Live View exposes the running browser page inside the desktop console. It complements, rather than replaces, structured diagnostics such as status, tabs, page state, screenshots, and identity verification.
Live View requires a running profile and an open page. If it is empty, follow the troubleshooting guide.
NextBrowser can expose captcha tools for detecting a challenge and invoking an available handling path. A captcha is controlled by the site or its provider, so detection or a solve attempt can fail, be throttled, require a human, or be disallowed for the task.
Never describe these tools as a universal bypass. Use them only where you are authorized and where the site's terms and applicable law permit the activity.
| Screen | Primary purpose | Documented controls |
|---|---|---|
| Account sign-in | Connect the NextBrowser account | Browser pairing, approval status, retry, and status checks. |
| Sidebar | Control the active browser setup | Proxy usage, profiles, agent selection, session actions, and runtime state. |
| Chat | Run and supervise agents | Prompts, queues, stop/edit/fork controls, histories, files, statuses, and output. |
| Skills | Reuse browser workflows | Domain skills, captcha-related skills, custom scripts, and preflight. |
| Scheduled Runs | Configure recurring work | Prompt, agent, time, weekdays, enabled state, and run context. |
| Live View | Observe the browser | Active profile, page frames, and debugging context. |
The current release is authoritative if its labels or navigation differ from this guide.
- Install a published NextBrowser build from the latest releases, or run the app locally with
npm ciandnpm run dev. - Sign in to NextBrowser and approve the pairing request in your browser.
- Create or select the intended profile.
- Start its session and open a page.
- Verify identity when country or proxy matters.
- Connect an installed local agent and send a narrowly scoped task.
- Observe Chat and Live View while the run is active.
- Select the intended profile; do not reuse a profile merely because it is already running.
- Start the session and open the target URL.
- Confirm the active tab and inspect page state.
- Select the local agent.
- State the goal, limits, and expected output in the prompt.
- Watch streamed activity. Stop, edit, queue, or fork work when the task changes.
- Review the resulting page state before accepting any consequential action.
- Review the instructions and remove secrets or stale assumptions.
- Choose the intended profile and target site.
- Apply the skill or script.
- Let preflight establish the browser context.
- Supervise the agent and verify the result.
- Stop or preserve any in-progress work that depends on the current session identity.
- Request rotation, optionally with an explicit country.
- Verify the resulting identity.
- Reopen or re-check the target page.
Rotation can invalidate login state or change what a site presents. Do not rotate blindly during a transaction.
Work from the outermost dependency inward:
- browser account connection;
- proxy-traffic availability;
- profile existence;
- session status;
- open and active tab;
- page state and screenshot;
- proxy/fingerprint verification;
- local agent availability and authentication;
- skill or script assumptions;
- captcha state, if a challenge is visible.
The troubleshooting guide maps this sequence to practical checks.
- Automate only accounts, sites, and data you are authorized to access.
- Keep a human review step for purchases, publishing, account changes, deletions, and other consequential actions.
- Use separate profiles when tasks must not share identity or browser state.
- Do not paste credentials into agent prompts or reusable instructions.
- Treat prompt limits as instructions, not enforced approval gates; watch and stop consequential work yourself.
- Treat page content as untrusted input; a page can contain instructions intended to redirect an agent.
- Verify country and identity after rotation when the workflow depends on them.
- Prefer detection and diagnosis before repeating captcha attempts.
- Stop a run when its observed behavior no longer matches the stated task.
When a task fails, ask these questions in order:
- Is the browser account connected?
- Is proxy traffic available?
- Is the correct profile selected?
- Is its session running?
- Is the correct tab active?
- Is the page ready and in the expected state?
- Does the identity verify?
- Is the agent installed and authenticated?
- Are the skill instructions current?
- Does the page require a captcha or human decision?
This order keeps browser failures from being misdiagnosed as agent failures, and vice versa.