Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
fix(cli): prevent orphaned server processes with flock-based locking
ShawnPanac8242e7edd76
diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex 2538fbbd8..0d4b1e84f 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -213,12 +213,14 @@ def get_session_metadata_path(session: str) -> Path:def ensure_server(session: str, browser: str, headed: bool, profile: str | None, api_key: str | None) -> bool:"""Start server if not running. Returns True if started."""+ from browser_use.skill_cli.utils import is_session_locked, kill_orphaned_server+meta_path = get_session_metadata_path(session)- # Check if server is already running and responsive- if is_server_running(session):+ # Check if server is already running AND holding its lock (healthy server)+ if is_server_running(session) and is_session_locked(session):try:- sock = connect_to_server(session, timeout=0.1)+ sock = connect_to_server(session, timeout=0.5) # Increased from 0.1ssock.close()# Check browser mode matches existing session@@ -248,7 +250,10 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,return False # Already running with correct modeexcept Exception:- pass # Server dead, restart+ pass # Server not responsive, continue to restart logic++ # Kill any orphaned server (has PID file but no lock)+ kill_orphaned_server(session)# Build server commandcmd = [@@ -291,11 +296,11 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,stderr=subprocess.DEVNULL,)- # Wait for server to be ready+ # Wait for server to be ready (must have PID, lock, and responsive socket)for _ in range(100): # 5 seconds max- if is_server_running(session):+ if is_server_running(session) and is_session_locked(session):try:- sock = connect_to_server(session, timeout=0.1)+ sock = connect_to_server(session, timeout=0.5)sock.close()# Write metadata file to track session configdiff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.pyindex 859473f3c..67b8dace5 100644--- a/browser_use/skill_cli/server.py+++ b/browser_use/skill_cli/server.py@@ -13,6 +13,9 @@ import osimport signalimport sysfrom pathlib import Path+from typing import IO++import portalocker# Configure logging before importslogging.basicConfig(@@ -40,6 +43,7 @@ class SessionServer:self.running = Trueself._server: asyncio.Server | None = Noneself._shutdown_event: asyncio.Event | None = None+ self._lock_file: IO | None = None# Lazy import to avoid loading everything at startupfrom browser_use.skill_cli.sessions import SessionRegistry@@ -165,9 +169,25 @@ class SessionServer:async def run(self) -> None:"""Run the server."""- from browser_use.skill_cli.utils import get_pid_path, get_socket_path+ from browser_use.skill_cli.utils import get_lock_path, get_pid_path, get_socket_path++ # Acquire exclusive lock BEFORE writing PID - this prevents race conditions+ lock_path = get_lock_path(self.session_name)+ lock_path.parent.mkdir(parents=True, exist_ok=True)+ lock_path.touch(exist_ok=True)++ self._lock_file = open(lock_path, 'r+') # noqa: ASYNC230 - blocking ok at startup+ try:+ portalocker.lock(self._lock_file, portalocker.LOCK_EX | portalocker.LOCK_NB)+ except portalocker.LockException:+ logger.error(f'Another server is already running for session: {self.session_name}')+ self._lock_file.close()+ self._lock_file = None+ sys.exit(1)++ logger.info(f'Acquired exclusive lock for session: {self.session_name}')- # Write PID file+ # NOW safe to write PID filepid_path = get_pid_path(self.session_name)pid_path.write_text(str(os.getpid()))logger.info(f'PID file: {pid_path}')@@ -229,6 +249,14 @@ class SessionServer:except asyncio.CancelledError:passfinally:+ # Release lock on shutdown+ if self._lock_file:+ try:+ portalocker.unlock(self._lock_file)+ self._lock_file.close()+ except Exception:+ pass+ self._lock_file = Nonelogger.info('Server stopped')diff --git a/browser_use/skill_cli/utils.py b/browser_use/skill_cli/utils.pyindex e20338b1e..c999bb89c 100644--- a/browser_use/skill_cli/utils.py+++ b/browser_use/skill_cli/utils.py@@ -3,10 +3,14 @@import hashlibimport osimport platform+import signalimport subprocessimport sysimport tempfilefrom pathlib import Path+from typing import IO++import portalockerdef get_socket_path(session: str) -> str:@@ -33,6 +37,11 @@ def get_log_path(session: str) -> Path:return Path(tempfile.gettempdir()) / f'browser-use-{session}.log'+def get_lock_path(session: str) -> Path:+ """Get lock file path for session."""+ return Path(tempfile.gettempdir()) / f'browser-use-{session}.lock'++def _pid_exists(pid: int) -> bool:"""Check if a process with given PID exists.@@ -69,6 +78,85 @@ def is_server_running(session: str) -> bool:return False+def try_acquire_server_lock(session: str) -> IO | None:+ """Try to acquire the server lock non-blocking.++ Returns:+ Lock file handle if acquired (caller must keep in scope to maintain lock),+ None if lock is already held by another process.+ """+ lock_path = get_lock_path(session)+ lock_path.parent.mkdir(parents=True, exist_ok=True)+ lock_path.touch(exist_ok=True)++ lock_file = open(lock_path, 'r+')+ try:+ portalocker.lock(lock_file, portalocker.LOCK_EX | portalocker.LOCK_NB)+ return lock_file+ except portalocker.LockException:+ lock_file.close()+ return None+++def is_session_locked(session: str) -> bool:+ """Check if session has an active lock (server is holding it)."""+ lock_path = get_lock_path(session)+ if not lock_path.exists():+ return False++ try:+ with open(lock_path, 'r+') as f:+ portalocker.lock(f, portalocker.LOCK_EX | portalocker.LOCK_NB)+ portalocker.unlock(f)+ return False # Lock acquired = no one holding it+ except portalocker.LockException:+ return True # Lock failed = someone holding it+ except OSError:+ return False # File access error+++def kill_orphaned_server(session: str) -> bool:+ """Kill an orphaned server (has PID file but no lock).++ An orphaned server is one where the process is running but it doesn't+ hold the session lock (e.g., because a newer server took over the lock+ file but didn't kill the old process).++ Returns:+ True if an orphan was found and killed.+ """+ pid_path = get_pid_path(session)+ if not pid_path.exists():+ return False++ # Check if session is locked (server alive and holding lock)+ if is_session_locked(session):+ return False # Not an orphan - server is healthy++ # PID exists but no lock - orphan situation+ try:+ pid = int(pid_path.read_text().strip())+ if _pid_exists(pid):+ # Kill the orphaned process+ if sys.platform == 'win32':+ import ctypes++ PROCESS_TERMINATE = 1+ handle = ctypes.windll.kernel32.OpenProcess(PROCESS_TERMINATE, False, pid)+ if handle:+ ctypes.windll.kernel32.TerminateProcess(handle, 1)+ ctypes.windll.kernel32.CloseHandle(handle)+ else:+ os.kill(pid, signal.SIGKILL)+ return True+ except (OSError, ValueError):+ pass++ # Clean up stale files even if we couldn't kill (process may be gone)+ cleanup_session_files(session)+ return False++def find_all_sessions() -> list[str]:"""Find all running browser-use sessions by scanning PID files."""sessions = []@@ -82,9 +170,11 @@ def find_all_sessions() -> list[str]:def cleanup_session_files(session: str) -> None:- """Remove session socket and PID files."""+ """Remove session socket, PID, lock, and metadata files."""sock_path = get_socket_path(session)pid_path = get_pid_path(session)+ lock_path = get_lock_path(session)+ meta_path = Path(tempfile.gettempdir()) / f'browser-use-{session}.meta'# Remove socket file (Unix only)if not sock_path.startswith('tcp://'):@@ -99,6 +189,18 @@ def cleanup_session_files(session: str) -> None:except OSError:pass+ # Remove lock file+ try:+ lock_path.unlink()+ except OSError:+ pass++ # Remove metadata file+ try:+ meta_path.unlink()+ except OSError:+ pass+def find_chrome_executable() -> str | None:"""Find Chrome/Chromium executable on the system."""diff --git a/tests/ci/test_server_locking.py b/tests/ci/test_server_locking.pynew file mode 100644index 000000000..e5ee296ee--- /dev/null+++ b/tests/ci/test_server_locking.py@@ -0,0 +1,255 @@+"""Tests for server locking to prevent race conditions."""++import os+import subprocess+import sys+import tempfile+import time+from pathlib import Path++import portalocker+import pytest++from browser_use.skill_cli.utils import (+ cleanup_session_files,+ get_lock_path,+ get_pid_path,+ is_server_running,+ is_session_locked,+ kill_orphaned_server,+ try_acquire_server_lock,+)+++def test_session():+ """Provide a unique test session name and cleanup after."""+ session = f'test-lock-{os.getpid()}-{time.time_ns()}'+ yield session+ cleanup_session_files(session)+++def test_lock_path_generation(test_session):+ """Test that lock path is generated correctly."""+ path = get_lock_path(test_session)+ assert path.parent == Path(tempfile.gettempdir())+ assert path.name == f'browser-use-{test_session}.lock'+++def test_try_acquire_server_lock_success(test_session):+ """Test acquiring lock when no one holds it."""+ lock = try_acquire_server_lock(test_session)+ assert lock is not None++ # Should block second acquisition+ lock2 = try_acquire_server_lock(test_session)+ assert lock2 is None++ # Release first lock+ portalocker.unlock(lock)+ lock.close()++ # Now should succeed+ lock3 = try_acquire_server_lock(test_session)+ assert lock3 is not None+ portalocker.unlock(lock3)+ lock3.close()+++def test_is_session_locked(test_session):+ """Test detecting if session is locked."""+ # Initially not locked+ assert is_session_locked(test_session) is False++ # Acquire lock+ lock = try_acquire_server_lock(test_session)+ assert lock is not None++ # Now should be locked+ assert is_session_locked(test_session) is True++ # Release+ portalocker.unlock(lock)+ lock.close()++ # No longer locked+ assert is_session_locked(test_session) is False+++def test_kill_orphaned_server_no_pid_file(test_session):+ """Test that kill_orphaned_server returns False when no PID file."""+ assert kill_orphaned_server(test_session) is False+++def test_kill_orphaned_server_with_lock(test_session):+ """Test that kill_orphaned_server doesn't kill server holding lock."""+ # Create PID file pointing to current process+ pid_path = get_pid_path(test_session)+ pid_path.write_text(str(os.getpid()))++ # Acquire lock (simulating a healthy server)+ lock = try_acquire_server_lock(test_session)+ assert lock is not None++ # Should not kill - server is healthy (has lock)+ assert kill_orphaned_server(test_session) is False++ portalocker.unlock(lock)+ lock.close()+++def test_cleanup_includes_lock_file(test_session):+ """Test that cleanup removes lock file."""+ lock_path = get_lock_path(test_session)+ pid_path = get_pid_path(test_session)++ # Create files+ lock_path.touch()+ pid_path.write_text('12345')++ assert lock_path.exists()+ assert pid_path.exists()++ cleanup_session_files(test_session)++ assert not lock_path.exists()+ assert not pid_path.exists()+++def test_concurrent_lock_acquisition(test_session):+ """Test that only one process can hold the lock."""+ lock_path = get_lock_path(test_session)+ lock_path.parent.mkdir(parents=True, exist_ok=True)+ lock_path.touch()++ # Acquire lock in current process+ lock = try_acquire_server_lock(test_session)+ assert lock is not None++ # Try to acquire in subprocess - should fail+ result = subprocess.run(+ [+ sys.executable,+ '-c',+ f'''+import portalocker+from pathlib import Path++lock_path = Path("{lock_path}")+f = open(lock_path, 'r+')+try:+ portalocker.lock(f, portalocker.LOCK_EX | portalocker.LOCK_NB)+ print("ACQUIRED")+except portalocker.LockException:+ print("BLOCKED")+f.close()+''',+ ],+ capture_output=True,+ text=True,+ timeout=5,+ )++ assert 'BLOCKED' in result.stdout++ # Release lock+ portalocker.unlock(lock)+ lock.close()++ # Now subprocess should succeed+ result = subprocess.run(+ [+ sys.executable,+ '-c',+ f'''+import portalocker+from pathlib import Path++lock_path = Path("{lock_path}")+f = open(lock_path, 'r+')+try:+ portalocker.lock(f, portalocker.LOCK_EX | portalocker.LOCK_NB)+ print("ACQUIRED")+ portalocker.unlock(f)+except portalocker.LockException:+ print("BLOCKED")+f.close()+''',+ ],+ capture_output=True,+ text=True,+ timeout=5,+ )++ assert 'ACQUIRED' in result.stdout+++def test_lock_released_on_process_death(test_session):+ """Test that lock is automatically released when process dies."""+ lock_path = get_lock_path(test_session)+ lock_path.parent.mkdir(parents=True, exist_ok=True)+ lock_path.touch()++ # Start subprocess that holds lock+ proc = subprocess.Popen(+ [+ sys.executable,+ '-c',+ f'''+import portalocker+import time+from pathlib import Path++lock_path = Path("{lock_path}")+f = open(lock_path, 'r+')+portalocker.lock(f, portalocker.LOCK_EX | portalocker.LOCK_NB)+print("LOCKED", flush=True)+time.sleep(60) # Hold lock+''',+ ],+ stdout=subprocess.PIPE,+ text=True,+ )++ # Wait for lock acquisition+ line = proc.stdout.readline()+ assert 'LOCKED' in line++ # Verify we can't acquire+ lock = try_acquire_server_lock(test_session)+ assert lock is None++ # Kill the process+ proc.terminate()+ proc.wait(timeout=5)++ # Small delay for OS to release lock+ time.sleep(0.1)++ # Now we should be able to acquire+ lock = try_acquire_server_lock(test_session)+ assert lock is not None+ portalocker.unlock(lock)+ lock.close()+++def test_is_server_running_without_pid(test_session):+ """Test is_server_running returns False when no PID file."""+ assert is_server_running(test_session) is False+++def test_is_server_running_with_current_pid(test_session):+ """Test is_server_running returns True when PID file points to live process."""+ pid_path = get_pid_path(test_session)+ pid_path.write_text(str(os.getpid()))++ assert is_server_running(test_session) is True+++def test_is_server_running_with_dead_pid(test_session):+ """Test is_server_running returns False when PID file points to dead process."""+ pid_path = get_pid_path(test_session)+ # Use a PID that's very unlikely to exist+ pid_path.write_text('999999999')++ assert is_server_running(test_session) is False