kill headless from sdk and add open_viewer (#615)

Author: andreakiro

README.md

@@ -65,7 +65,7 @@ import os
 
 client = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))
 
-with client.Session(headless=False) as session:
+with client.Session(open_viewer=True) as session:
     agent = client.Agent(session=session, reasoning_model='gemini/gemini-2.5-flash', max_steps=30)
     response = agent.run(task="doom scroll cat memes on google images")
 ```
@@ -103,7 +103,7 @@ class TopPosts(BaseModel):
     posts: list[HackerNewsPost]
 
 client = NotteClient()
-with client.Session(headless=False, browser_type="firefox") as session:
+with client.Session(open_viewer=True, browser_type="firefox") as session:
     agent = client.Agent(session=session, reasoning_model='gemini/gemini-2.5-flash', max_steps=15)
     response = agent.run(
         task="Go to Hacker News (news.ycombinator.com) and extract the top 5 posts with their titles, URLs, points, authors, and comment counts.",
@@ -120,7 +120,7 @@ from notte_sdk import NotteClient
 
 client = NotteClient()
 
-with client.Vault() as vault, client.Session(headless=False) as session:
+with client.Vault() as vault, client.Session(open_viewer=True) as session:
     vault.add_credentials(
         url="https://x.com",
         username="your-email",
@@ -143,7 +143,7 @@ from notte_sdk import NotteClient
 client = NotteClient()
 
 with client.Persona(create_phone_number=False) as persona:
-    with client.Session(browser_type="firefox", headless=False) as session:
+    with client.Session(browser_type="firefox", open_viewer=True) as session:
         agent = client.Agent(session=session, persona=persona, max_steps=15)
         response = agent.run(
             task="Open the Google form and RSVP yes with your name",
@@ -169,7 +169,7 @@ with client.Session(
     solve_captchas=True,
     proxies=True,  # US-based proxy
     browser_type="firefox",
-    headless=False
+    open_viewer=True
 ) as session:
     agent = client.Agent(session=session, max_steps=5)
     response = agent.run(
@@ -278,7 +278,7 @@ from notte_sdk import NotteClient
 
 client = NotteClient()
 
-with client.Session(headless=False, perception_type="fast") as session:
+with client.Session(open_viewer=True, perception_type="fast") as session:
     # Script execution for deterministic navigation
     session.execute({"type": "goto", "url": "https://www.quince.com/women/organic-stretch-cotton-chino-short"})
     session.observe()

docs/src/intro/quickstart.mdx

@@ -28,7 +28,7 @@ In this quickstart guide, we'll create a simple web agent that can browse and in
     client = NotteClient(api_key="your-key-here")
 
     # create a browser session resource
-    with client.Session(headless=False) as session:
+    with client.Session(open_viewer=True) as session:
 
         # attach an agent to session
         agent = client.Agent(

docs/src/snippets/personas/create_account.mdx

@@ -12,7 +12,7 @@ url = "https://console.notte.cc"
 # create credentials for the persona (automatically generates a password and stores it in the vault)
 persona.add_credentials(url=url)
 
-with notte.Session(headless=False) as session:
+with notte.Session(open_viewer=True) as session:
 	agent = notte.Agent(session=session, persona=persona)
 	response = agent.run(task=f"Go to {url} and create an account. Go create an API key and return the API key.", url=url)
 	print(response.answer)

examples/auth-vault-agent/agent.py

@@ -12,7 +12,7 @@ def main():
     # - GITHUB_COM_PASSWORD: your github password
     notte = NotteClient()
 
-    with notte.Vault() as vault, notte.Session(headless=False) as session:
+    with notte.Vault() as vault, notte.Session(open_viewer=True) as session:
         vault.add_credentials_from_env("github.com")
         agent = notte.Agent(vault=vault, session=session)
         output = agent.run(task="Go to github.com, and login with your provided credentials")

examples/cli_agent.py

@@ -11,9 +11,9 @@
 def main(
     task: Annotated[str, typer.Option(..., help="Task to perform")],
     reasoning_model: Annotated[str, typer.Option(help="Reasoning model to use")] = LlmModel.default(),  # type: ignore[reportArgumentType]
-    headless: Annotated[bool, typer.Option(help="Run in headless mode")] = False,
+    open_viewer: Annotated[bool, typer.Option(help="Open live viewer")] = False,
 ) -> AgentResponse:
-    with notte.Session(headless=headless) as session:
+    with notte.Session(open_viewer=open_viewer) as session:
         agent = notte.Agent(reasoning_model=reasoning_model, session=session)
         return agent.run(task=task)
 

examples/email-notifier-agent/agent.py

@@ -21,7 +21,7 @@ def main():
             receiver_email=str(os.environ["EMAIL_RECEIVER"]),
         )
     )
-    with notte.Session(headless=False) as session:
+    with notte.Session(open_viewer=True) as session:
         notifier_agent = notte.Agent(notifier=notifier, session=session)
 
         response = notifier_agent.run(task="Make a summary of the financial times latest news")

examples/order-on-ubereats/agent.py

@@ -41,7 +41,7 @@ def main():
         card_full_expiration="CREDIT_CARD_EXPIRATION",
     )
 
-    with notte.Session(headless=False) as session:
+    with notte.Session(open_viewer=True) as session:
         with notte.Vault() as vault:
             vault.add_credentials(url="uber.com", **load_env_vars(cred_env_vars))
             vault.set_credit_card(**load_env_vars(cc_env_vars))

examples/quickstart.py

@@ -17,6 +17,6 @@
 
     client = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))
 
-    with client.Session(headless=False) as session:
+    with client.Session(open_viewer=True) as session:
         agent = client.Agent(reasoning_model=reasoning_model, max_steps=max_steps, session=session)
         response = agent.run(task=task)

examples/quickstart_launcher.py

@@ -19,7 +19,7 @@
 def run_notte_quickstart(task: str, max_steps: int, reasoning_model: str):
     client = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))
 
-    with client.Session(headless=False) as session:
+    with client.Session(open_viewer=True) as session:
         agent = client.Agent(reasoning_model=reasoning_model, max_steps=max_steps, session=session)
         agent.run(task=task)
 

examples/scrape-nike-products/agent.py

@@ -112,7 +112,7 @@ def scrape_nike_products():
     run_dir = RESULT_DIR / timestamp
     run_dir.mkdir(exist_ok=True, parents=True)
 
-    with notte.Session(headless=False) as session:
+    with notte.Session(open_viewer=True) as session:
         categories = scrape_categories(session)
         _ = (run_dir / "categories.json").write_text(categories.model_dump_json())
         outputs: list[list[ShoppingItem]] = []