PersistentSessionsProtocol v0.1.0

A unified approach to browser session persistence across frameworks

GitHub Protocol Spec Getting Started Examples

GitHub stars npm

One Solution for Session Persistence

The PersistentSessionsProtocol (PSP) creates a standardized approach for browser automation tools to save, share, and restore session data across different frameworks and machines. This protocol bridges the critical gap in browser automation by providing a framework-agnostic method for persisting state, significantly reducing authentication friction and improving testing reliability.

npm install @psp/core @psp/playwright

Key Features

Cross-Framework Compatibility

Works with Playwright, Selenium, Puppeteer, Skyvern, Stagehand, and other major automation tools.

Complete State Capture

Preserves cookies, localStorage, sessionStorage, and authentication tokens.

Flexible Storage Options

Support for local filesystem, Redis, database, and cloud storage backends.

Secure by Design

Encryption for sensitive session data with configurable security levels.

Session Recording & Replay

Capture and reproduce user interactions across environments.

REST and WebSocket APIs

For server-based session management and real-time updates.

AI Agent Integration

Optimized for use with AI agents and browser automation.

High Performance

Efficient session capture and restoration with minimal overhead.

Modern UI Dashboard

PSP includes a responsive dashboard for managing sessions across different frameworks, providing real-time updates and detailed analytics.

PSP Dashboard

Dashboard Features

  • Create, view, edit, and delete browser sessions
  • Real-time updates of session changes via WebSockets
  • Session recording and playback capabilities
  • Cross-framework session management
  • Light and dark modes for comfortable viewing
  • Responsive design for desktop and mobile devices
Getting Started with the Dashboard
cd packages/ui
npm install
npm start

For development with mock data:

REACT_APP_USE_MOCK_API=true npm start

Quick Start

import { chromium } from 'playwright';
import { PlaywrightAdapter } from '@psp/playwright';

// Initialize Playwright
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();

// Create PSP adapter and session
const adapter = new PlaywrightAdapter();
const session = await adapter.createSession(page, {
  name: 'my-auth-session',
  storage: 'local'
});

// Navigate and log in
await page.goto('https://example.com/login');
await page.fill('input[name="username"]', 'user');
await page.fill('input[name="password"]', 'pass');
await page.click('button[type="submit"]');

// Wait for login to complete
await page.waitForNavigation();

// Capture the authenticated session
await session.capture();
console.log(`Session saved with ID: ${session.getId()}`);

// Later, restore the session in a new browser
const newBrowser = await chromium.launch();
const newContext = await newBrowser.newContext();
const newPage = await newContext.newPage();

// Load the saved session
const savedSession = await adapter.loadSession(session.getId());
await savedSession.restore(newPage);

// Now the new page has the authenticated session
await newPage.goto('https://example.com/dashboard');
// Already logged in!
# Create a PSP session with Selenium
from psp.client import SeleniumAdapter
from selenium import webdriver

# Initialize driver
driver = webdriver.Chrome()

# Create adapter and session
adapter = SeleniumAdapter()
session = adapter.create_session(driver, 
  name="my-authentication-session",
  storage="cloud"  # or 'local', 'redis', etc.
)

# Log in to your application
driver.get("https://example.com/login")
driver.find_element_by_name("username").send_keys("user")
driver.find_element_by_name("password").send_keys("pass")
driver.find_element_by_xpath("//button[@type='submit']").click()

# Capture the authenticated session
session.capture()

# Later, restore the session
new_driver = webdriver.Chrome()
session.restore(new_driver)
# Now new_driver has the same authenticated session
const puppeteer = require('puppeteer');
const { PuppeteerAdapter } = require('@psp/puppeteer');

async function example() {
  // Initialize Puppeteer
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  
  // Create PSP adapter and session
  const adapter = new PuppeteerAdapter();
  const session = await adapter.createSession(page, {
    name: 'my-auth-session',
    storage: 'local'
  });
  
  // Navigate and log in
  await page.goto('https://example.com/login');
  await page.type('input[name="username"]', 'user');
  await page.type('input[name="password"]', 'pass');
  await page.click('button[type="submit"]');
  
  // Wait for login to complete
  await page.waitForNavigation();
  
  // Capture the authenticated session
  await session.capture();
  console.log(`Session saved with ID: ${session.getId()}`);
  
  // Later, restore the session in a new browser
  const newBrowser = await puppeteer.launch();
  const newPage = await newBrowser.newPage();
  
  // Load the saved session
  const savedSession = await adapter.loadSession(session.getId());
  await savedSession.restore(newPage);
  
  // Now the new page has the authenticated session
  await newPage.goto('https://example.com/dashboard');
  // Already logged in!
}

Documentation

Getting Started

Complete guide to installing PSP and implementing your first session capture and restore.

View Guide
Protocol Specification

Detailed documentation of the protocol architecture and data model.

View Protocol Docs
Example Implementations

Code examples showing how to use PSP with various frameworks.

View Examples

Use Cases

Bypassing Authentication in Automated Tests

Use PSP to log in once, then reuse the same authenticated session for all your subsequent tests. This dramatically speeds up test suites by eliminating the need to go through authentication flows for each test.

Cross-Framework Session Sharing

Capture a session with Playwright and restore it in Selenium or Puppeteer. This allows teams using different automation frameworks to share sessions without duplicating work.

AI Agent Browser Memory

Let AI agents maintain state between different browser automation sessions, providing continuity when building complex workflows that span multiple interactions.

Handling Multi-Step Workflows

For complex user journeys that involve many steps, save checkpoints along the way so you can quickly restore to any point in the process for debugging or continued development.

Supported Frameworks

Web Automation
  • Playwright - @psp/playwright
  • Selenium - @psp/selenium
  • Puppeteer - @psp/puppeteer
AI & ML Tools
  • Browser-Use - @psp/browser-use
  • Computer-Use - @psp/computer-use
  • Skyvern - psp-skyvern
  • Stagehand - @psp/stagehand
Cloud Environments
  • Cloudflare Workers - @psp/cloudflare
  • Lambda Environments - @psp/lambda (Coming Soon)

Storage Options

Local Storage

PSP supports local storage options for development and testing:

  • Filesystem - Built into @psp/core
  • In-Memory - For ephemeral sessions
Remote Storage

For team environments and production use, PSP supports:

  • Redis - For high-performance cache
  • Cloud Storage - AWS S3, Google Cloud Storage, Azure Blob
  • Database - MongoDB, PostgreSQL (via adapters)

Architecture

PSP employs a layered architecture with four main components:

  1. Session Capture Layer - Extracts state using browser-specific adapters
  2. Serialization Layer - Handles data encoding and transmission
  3. Storage Layer - Manages persistent storage of session data
  4. Replay Layer - Restores sessions across different environments

This design ensures flexibility while maintaining compatibility across different frameworks. For more details, see the Protocol Specification.