Browser Use Terminal - Browser Use

Browser Use Terminal is a Codex-style assistant for the browser. Coding assistants like Claude Code and Codex work well because they give the model autonomy and a real environment to operate in. They provide tools, files, shell commands, history, resumable sessions, and a terminal UI where you can watch and steer the work. Browser Use Terminal brings that pattern to browser automation. It gives an AI agent its own browser environment: it can control Chrome, see screenshots, inspect pages, run page JavaScript, save files, use browser profiles, handle secrets, and keep a history of what happened. Learn more on the Browser Use Terminal site or view the Terminal GitHub repo. In practice, this means you can ask for browser work from your terminal:

Find the cancellation policy for my current hotel reservation.

Give this employee admin permission in Azure.

Research the top Hacker News stories and summarize the points.

You can use Browser Use Terminal in three ways:

Surface	What it is for
TUI	The interactive terminal app you launch with `browser`. Best for normal, hands-on use.
CLI	Scriptable commands such as `browser-use-terminal run-openai`. Best for automation and one-off tasks.
Python	`browser_use.beta.Agent`, backed by the same Rust runtime. Best when you want browser-use code with terminal runtime behavior.

Browser Use Terminal is separate from the lower-level browser-use CLI. Use browser for the Terminal TUI, browser-use-terminal for Terminal task commands, and browser-use for direct browser-control commands.

Terms

TUI: terminal user interface. This is the interactive app you open with browser.
CLI: command-line interface. These are scriptable commands such as browser-use-terminal run-openai.
Headless browser: a browser that runs without a visible window.
CDP: Chrome DevTools Protocol. This lets Browser Use connect to an existing Chrome instance.
MCP: Model Context Protocol. This lets the agent use tools from external MCP servers.
TOTP: time-based one-time password. This is the six-digit code generated by authenticator apps for 2FA.

Install

Install Browser Use Terminal:

curl -fsSL https://browser-use.com/terminal/install.sh | sh

Restart your shell or source your shell profile if the installer updates your PATH. Verify the two terminal executables:

which browser
which browser-use-terminal
browser-use-terminal --help

Open the TUI:

browser

Set up Python usage in the same project where you will write your agent code:

uv venv --python 3.12
source .venv/bin/activate
uv pip install browser-use

TUI Commands

In the TUI, type / to open the command palette. These are the main commands:

Command	What it does
`/task`	Start a new task.
`/model`	Choose the model and provider.
`/auth`	Sign in to a provider.
`/browser`	Change the browser backend.
`/profile`	Choose the default Chrome profile.
`/history`	Browse previous tasks.
`/context`	Inspect context window attribution.
`/secrets`	Save passwords and 2FA setup keys for website logins.
`/import-passwords`	Import saved logins from 1Password.
`/domains`	Allow or block which sites the agent can visit.
`/sync-cookies`	Sync local cookies.
`/email`	Give the agent a disposable inbox for sign-ups, links, and codes.
`/goal`	Set or view the goal for a long-running task.
`/feedback`	Report a bug or share feedback.
`/update`	Install the latest release.
`/reload`	Restart the UI in this terminal.
`/exit`	Quit Browser Use Terminal.

Run Browser Tasks

TUI

The TUI is the main Browser Use Terminal experience:

browser

Type a browser task. You can watch the agent work, interrupt it, steer it, and continue the same session later.

Open my company's dashboard and summarize failed jobs from today.

Log in to the vendor portal and download the latest invoice.

CLI

Use one-shot commands for scripts, automation, and quick tasks:

browser-use-terminal --help

browser-use-terminal run-openai --model gpt-5.5 \
  "Go to https://news.ycombinator.com and return the top stories with points"

Other provider commands:

browser-use-terminal run-anthropic --model claude-sonnet-4-6 "Research Browser Use"
browser-use-terminal run-openrouter --model openai/gpt-5.5 "Research Browser Use"
browser-use-terminal run-deepseek --model deepseek-v4-pro "Research Browser Use"

Python

Use browser_use.beta.Agent to run Python code on top of the Rust terminal runtime:

uv pip install browser-use

import asyncio

from browser_use.beta import Agent, BrowserProfile, ChatOpenAI


async def main():
    agent = Agent(
        task="Go to https://news.ycombinator.com and return the top stories with points.",
        llm=ChatOpenAI(model="gpt-5.5"),
        browser_profile=BrowserProfile(
            headless=True,
            window_size={"width": 1440, "height": 900},
            allowed_domains=["news.ycombinator.com"],
        ),
    )

    history = await agent.run(max_steps=12)
    print(history.final_result())


asyncio.run(main())

Configure Models

TUI

Use /auth to sign in and configure credentials, then /model to choose the model:

/auth
/model

This is the recommended setup path for normal interactive use.

CLI

For one-shot commands and CI, set the provider key for the provider command you are using:

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export OPENROUTER_API_KEY=...
export DEEPSEEK_API_KEY=...
export BROWSER_USE_API_KEY=...

Then choose a provider command and model:

browser-use-terminal run-openai --model gpt-5.5 "Research Browser Use"
browser-use-terminal run-anthropic --model claude-sonnet-4-6 "Research Browser Use"
browser-use-terminal run-openrouter --model openai/gpt-5.5 "Research Browser Use"
browser-use-terminal run-deepseek --model deepseek-v4-pro "Research Browser Use"

Python

Pass a supported browser-use model class to Agent:

from browser_use.beta import Agent, ChatAnthropic

agent = Agent(
    task="Find the latest Browser Use docs update",
    llm=ChatAnthropic(model="claude-sonnet-4-6"),
)

Supported Python model classes:

Python model class	Example
`ChatOpenAI`	`ChatOpenAI(model="gpt-5.5")`
`ChatAnthropic`	`ChatAnthropic(model="claude-sonnet-4-6")`
`ChatLiteLLM`	`ChatLiteLLM(model="openai/gpt-5.5")`
`ChatDeepSeek`	`ChatDeepSeek(model="deepseek-v4-pro")`
`ChatOpenRouter`	`ChatOpenRouter(model="openai/gpt-5.5")`

Choose A Browser

TUI

Use /browser to choose how the agent should run the browser:

/browser

Common choices are your local Chrome, a headless browser, or Browser Use Cloud. Browser Use Cloud is the easiest option to get started: it gives you a free, one-click browser setup without managing a local Chrome profile. Use /profile to choose the default Chrome profile:

/profile

CLI

Use terminal config or one-off config overrides for browser settings:

browser-use-terminal \
  --config 'browser.headless=true' \
  --config 'browser.window_size={width=1440,height=900}' \
  run-openai "Open Hacker News"

Python

Managed local browser:

from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(
        headless=True,
        user_data_dir="./browser-profile",
        window_size={"width": 1280, "height": 900},
    ),
)

Headed browser:

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(headless=False),
)

Browser Use Cloud: Browser Use Cloud is the simplest remote browser option for Python too. Set BROWSER_USE_API_KEY, pass use_cloud=True, and the terminal runtime handles the cloud browser session.

from browser_use.beta import Agent, BrowserSession, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_session=BrowserSession(
        use_cloud=True,
        cloud_profile_id="profile-id",
        cloud_proxy_country_code="US",
        keep_alive=False,
    ),
)

Existing browser over CDP:

from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Open Hacker News",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(
        cdp_url="http://127.0.0.1:9333",
        user_agent="BrowserUseRemoteCDP/1.0",
    ),
)

Secrets let the agent fill credentials without exposing raw values to the model.

TUI

Use /auth for Browser Use account and model-provider authentication:

/auth

Use /secrets to save website login secrets and 2FA setup keys:

/secrets

Inside /secrets, press Ctrl-O to import logins from 1Password. You can also run:

/import-passwords

Name a TOTP secret otp and paste the authenticator setup key, not the current six-digit code.

CLI

Store a password:

printf '%s' "$PASSWORD" | browser-use-terminal secrets set \
  --domain example.com \
  --name password \
  --stdin

Store a TOTP seed for 2FA:

printf '%s' "$TOTP_SEED" | browser-use-terminal secrets set \
  --domain example.com \
  --name otp \
  --totp \
  --stdin

Import saved logins from 1Password:

browser-use-terminal secrets import
browser-use-terminal secrets list

The import command uses the op CLI. secrets list prints metadata only, never secret values.

Python

Python runs use the same terminal runtime and terminal state. Configure website secrets with the terminal commands above, then run the Python agent against the matching domain.

from browser_use.beta import Agent, BrowserProfile, ChatOpenAI

agent = Agent(
    task="Log in to example.com and summarize my dashboard.",
    llm=ChatOpenAI(model="gpt-5.5"),
    browser_profile=BrowserProfile(allowed_domains=["example.com"]),
)

Restrict Domains

Domain policy controls where the browser can navigate.

TUI

Use /domains to allow or block sites from the TUI:

/domains

CLI

browser-use-terminal domains allow news.ycombinator.com
browser-use-terminal domains deny '*.tracking.example'
browser-use-terminal domains list
browser-use-terminal domains clear

Python

Pass domain policy through BrowserProfile:

from browser_use.beta import BrowserProfile

profile = BrowserProfile(
    allowed_domains=["news.ycombinator.com"],
    prohibited_domains=["*.tracking.example"],
)

Use MCP Servers

MCP servers add external tools to the agent.

TUI

Add MCP servers to terminal config, then run the TUI normally:

browser

CLI

Create an MCP config:

[mcp_servers.local]
transport = "stdio"
command = "python"
args = ["./server.py"]

Pass it when you run a task:

browser-use-terminal --mcp-config ./mcp.toml run-openai \
  "Use the browser and MCP tools to complete this task"

Python

Python terminal-backed runs can use terminal MCP configuration through the same terminal runtime. Configure MCP servers in terminal config before starting the Python run.

Use Profiles And Config

Profiles let you keep separate terminal settings for different accounts, browsers, models, or workflows.

TUI

Use /profile to choose the default Chrome profile:

/profile

Open the terminal with a named terminal config profile:

browser --profile work

CLI

The terminal reads config from:

$BROWSER_USE_TERMINAL_HOME/config.toml

If BROWSER_USE_TERMINAL_HOME is not set, it uses:

~/.browser-use-terminal

Use a named profile to layer $BROWSER_USE_TERMINAL_HOME/<name>.config.toml on top of the base config:

browser-use-terminal --profile work run-openai "Research this pricing page"

Use --state-dir for an isolated run:

browser-use-terminal --state-dir /tmp/browser-use-terminal run-openai \
  "Open Hacker News and summarize the front page"

Python

Point Python at a terminal state directory:

export BROWSER_USE_TERMINAL_HOME=/path/to/state

Use a specific terminal binary:

export BROWSER_USE_TERMINAL_BINARY=/path/to/browser-use-terminal

Troubleshooting Setup

`browser` Or `browser-use-terminal` Not Found

Restart your terminal, then check whether the install location is on your PATH:

which browser
which browser-use-terminal
echo "$PATH"

If the commands are still missing, rerun the installer and copy any PATH instructions it prints:

curl -fsSL https://browser-use.com/terminal/install.sh | sh

Which Command Should I Use?

Goal	Command
Open the interactive Terminal app	`browser`
Run a one-shot Terminal agent task	`browser-use-terminal run-openai "..."`
Use Terminal runtime from Python	`browser_use.beta.Agent`
Directly control a browser with low-level commands	`browser-use open https://example.com`

Python Cannot Find `browser_use.beta`

Install or upgrade the Python package in the same environment you are running:

uv pip install --upgrade browser-use
python -c "from browser_use.beta import Agent; print('ok')"

Forwarded Python Settings

When you use browser_use.beta.Agent, these Python settings are forwarded to the Rust terminal SDK:

Python setting	Terminal SDK field
`llm.provider`, inferred from the chat model	`llm.provider`
`llm.model`	`llm.model`
`llm_timeout`	`llm.timeout`
`headless`	`browser.headless`
`keep_alive`	`browser.keep_alive`
`cloud_profile_id`, `profile_id`	`browser.profile_id`
`cloud_proxy_country_code`, `proxy_country_code`	`browser.proxy_country_code`
`cdp_url`	`browser.cdp_url`
`headers` / CDP headers	`browser.cdp_headers`
`user_agent`	`browser.user_agent`
`viewport`	`browser.viewport`
`window_size`	`browser.window_size`
`storage_state`	`browser.storage_state`
`downloads_path`	`browser.downloads_path`
`allowed_domains`	`browser.allowed_domains`
`prohibited_domains`	`browser.blocked_domains`
`state_dir`	`browser.state_dir`
`no_viewport`	`browser.no_viewport`
`accept_downloads`	`browser.accept_downloads`
`output_model_schema`	`output_schema`
`calculate_cost`	`calculate_cost`
`max_actions_per_step`	`max_actions_per_step`

The same Python Agent instance can continue a terminal-backed session across follow-up runs.

Cloud Browser Setup

Set BROWSER_USE_API_KEY and pass the cloud profile or proxy settings through BrowserSession.

1Password Import Setup

Install and sign in to the 1Password CLI:

op account list

Then import:

browser-use-terminal secrets import

TOTP Setup

Store the base32 TOTP seed with --totp, not the current six-digit code:

printf '%s' "$BASE32_TOTP_SEED" | browser-use-terminal secrets set \
  --domain example.com \
  --name otp \
  --totp \
  --stdin

​Terms

​Install

​TUI Commands

​Run Browser Tasks

​TUI

​CLI

​Python

​Configure Models

​TUI

​CLI

​Python

​Choose A Browser

​TUI

​CLI

​Python

​Use Secrets And Login

​TUI

​CLI

​Python

​Restrict Domains

​TUI

​CLI

​Python

​Use MCP Servers

​TUI

​CLI

​Python

​Use Profiles And Config

​TUI

​CLI

​Python

​Troubleshooting Setup

​browser Or browser-use-terminal Not Found

​Which Command Should I Use?

​Python Cannot Find browser_use.beta

​Forwarded Python Settings

​Cloud Browser Setup

​1Password Import Setup

​TOTP Setup

Terms

Install

TUI Commands

Run Browser Tasks

TUI

CLI

Python

Configure Models

TUI

CLI

Python

Choose A Browser

TUI

CLI

Python

Use Secrets And Login

TUI

CLI

Python

Restrict Domains

TUI

CLI

Python

Use MCP Servers

TUI

CLI

Python

Use Profiles And Config

TUI

CLI

Python

Troubleshooting Setup

`browser` Or `browser-use-terminal` Not Found

Which Command Should I Use?

Python Cannot Find `browser_use.beta`

Forwarded Python Settings

Cloud Browser Setup

1Password Import Setup

TOTP Setup