For AI agents: a documentation index is available at /llms.txt
Skip to main content

Agent

Interactive chat with the Browserless hosted agent. The LLM runs server-side and drives a browser for you.

Prerequisites
  • The latest Browserless CLI (npm install -g @browserless.io/cli). Run this command again to upgrade an existing installation before using --cloud-profile.
  • A Browserless API token from your account dashboard

Command: browserless agent [prompt]

The agent supports multi-turn conversations: type follow-up prompts at the > prompt. Previous prompts are recalled with the up arrow (history stored in ~/.browserless/agent_history, capped at 200 entries).

For tasks that need sign-in, upload a signed-in local browser profile with browserless profile upload --name <name> --browser <browser> --profile <local-profile>, then pass that cloud name with browserless agent --cloud-profile <name>. The CLI checks that the name is valid and the cloud profile exists before opening the agent connection. Run browserless profile list to find your cloud profile names. --cloud-profile selects a saved cloud profile; the upload command's --profile selects your local source browser profile.

A login-looking first prompt without --cloud-profile prints a tip instead of asking for credentials. Every first turn instructs the agent never to ask for passwords, API tokens, or other secrets, and to stop and suggest uploading or refreshing a profile if sign-in is still needed. This relies on the model following instructions, not server-side enforcement. Don't enter passwords or API tokens into the chat, even if the agent asks.

When the agent pauses for input (e.g. an MFA code), it prompts you inline. Press Enter on an empty line or Ctrl-C to exit.

Flags​

  • --cloud-profile <name> Ask the agent to open every new browser session with this saved cloud profile. Invalid or missing cloud profile names exit with code 2 before the WebSocket opens. Other preflight API failures keep their normal error codes.
  • --no-history Disable reading and writing prompt history.
  • --json Emit the final structured result as JSON to stdout. Streaming events still render during the turn, but only the end payload is written to stdout.

Examples​

Open the interactive REPL

browserless agent

Upload a browser profile that's signed in to GitHub, then pass its cloud name to the agent. Replace Personal with your local Chrome profile name. --only-domain github.com limits the upload to GitHub authentication state.

browserless profile upload \
--browser chrome --profile Personal --name github \
--only-domain github.com
browserless agent --cloud-profile github \
"Star browserless/browserless on GitHub"

FAQ & Troubleshooting​

The agent says it needs me to sign in

Sign in to the site in your local browser, then upload and use that profile as shown in the GitHub example above. Replace github.com with your site's domain and github with your cloud profile name; repeat --only-domain for any identity-provider domain the sign-in requires. If the cloud profile already exists, update it with browserless profile refresh --name <name>, replacing <name> with that same cloud profile name. A saved profile can exist without being signed in to the site you need. The CLI checks existence, not whether the site's session is still valid. One-time verification codes are still supported when the agent pauses for input; don't type passwords or API tokens into the chat.

The CLI command isn't recognized

Verify the CLI is installed globally with npm list -g @browserless.io/cli. If missing, run npm install -g @browserless.io/cli to install it.

How do I authenticate the CLI?

Run browserless auth and enter your API token when prompted. The token is stored locally for subsequent commands.

Next steps​

Was this page helpful?