Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

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.py
index 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.1s
sock.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 mode
except 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 command
cmd = [
@@ -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 config
diff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.py
index 859473f3c..67b8dace5 100644
--- a/browser_use/skill_cli/server.py
+++ b/browser_use/skill_cli/server.py
@@ -13,6 +13,9 @@ import os
import signal
import sys
from pathlib import Path
+from typing import IO
+
+import portalocker
# Configure logging before imports
logging.basicConfig(
@@ -40,6 +43,7 @@ class SessionServer:
self.running = True
self._server: asyncio.Server | None = None
self._shutdown_event: asyncio.Event | None = None
+ self._lock_file: IO | None = None
# Lazy import to avoid loading everything at startup
from 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 file
pid_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:
pass
finally:
+ # Release lock on shutdown
+ if self._lock_file:
+ try:
+ portalocker.unlock(self._lock_file)
+ self._lock_file.close()
+ except Exception:
+ pass
+ self._lock_file = None
logger.info('Server stopped')
diff --git a/browser_use/skill_cli/utils.py b/browser_use/skill_cli/utils.py
index e20338b1e..c999bb89c 100644
--- a/browser_use/skill_cli/utils.py
+++ b/browser_use/skill_cli/utils.py
@@ -3,10 +3,14 @@
import hashlib
import os
import platform
+import signal
import subprocess
import sys
import tempfile
from pathlib import Path
+from typing import IO
+
+import portalocker
def 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.py
new file mode 100644
index 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