Skip to main content

​
Overview

Persistent sessions let you save session state when a session ends, then restore that state in future sessions. Both browser and desktop sessions support persistence:
  • Browser sessions save cookies and storage state — useful for staying logged into websites across runs
  • Desktop sessions save a full VM snapshot — preserving installed software, files, and system configuration
This is useful for:
  • Staying logged into websites or desktop apps across automation runs
  • Preserving user preferences, installed software, and settings
  • Avoiding repeated authentication or setup flows

​
How It Works

  1. Create a persistent session with persistent: true
  2. Log in or perform actions
  3. Terminate the session - state is automatically saved
  4. Create a new session with environment_id set to the original session ID
  5. The new session starts with all saved state restored
The environment_id is the id returned by POST /computers when you created the original persistent session (e.g., comp_abc123). This is the same ID shown in the dashboard environments list.

​
Step 1: Create a Persistent Session

First, create a session with persistent: true and perform your login: 
from tzafon import Computer

client = Computer()

# Create a persistent session
with client.create(kind="browser", persistent=True) as computer:
    # Navigate to login page
    computer.navigate("https://example.com/login")
    computer.wait(2)

    # Click email field and type
    computer.click(600, 230)
    computer.type("user@example.com")

    # Click password field and type
    computer.click(600, 300)
    computer.type("your_password")

    # Click sign in button
    computer.click(600, 380)
    computer.wait(5)

    # Verify logged in
    result = computer.screenshot()
    print(f"Logged in: {computer.get_screenshot_url(result)}")

    # Save the session ID for later
    print(f"Session ID (save this): {computer.id}")

# Session ends - state is saved automatically

​
Step 2: Restore the Session

Later, create a new session using the saved environment_id: 
from tzafon import Computer

client = Computer()

# Restore from previous persistent session
saved_session_id = "comp_1275553034519934828"  # From Step 1

with client.create(
    kind="browser",
    environment_id=saved_session_id
) as computer:
    # Navigate to the site - you should already be logged in!
    computer.navigate("https://example.com")
    computer.wait(3)

    # Take a screenshot to verify logged-in state
    result = computer.screenshot()
    print(f"Still logged in: {computer.get_screenshot_url(result)}")

    # Continue with your automation...

​
Desktop Persistence

Desktop sessions work the same way — use persistent: true to save a VM snapshot, then environment_id to restore it. The full VM state is preserved, including installed packages, files, and running services. 
from tzafon import Computer

client = Computer()

# Create a persistent desktop session and set it up
with client.create(kind="desktop", persistent=True) as computer:
    # Install software, configure the environment
    computer.execute("sudo apt-get install -y nodejs")
    computer.execute("mkdir -p ~/project && cd ~/project && npm init -y")
    computer.wait(3)

    result = computer.screenshot()
    print(f"Setup complete: {computer.get_screenshot_url(result)}")
    print(f"Session ID (save this): {computer.id}")

# Session ends - full VM snapshot is saved
Restore the desktop environment later — all installed software and files will be intact: 
saved_session_id = "comp_1275553034519934828"  # From above

with client.create(
    kind="desktop",
    environment_id=saved_session_id
) as computer:
    # nodejs is already installed, project directory exists
    computer.execute("cd ~/project && node --version")
    computer.wait(2)

    result = computer.screenshot()
    print(f"Restored: {computer.get_screenshot_url(result)}")

​
Important Notes

Restoring does not automatically keep saving. If you pass environment_id without persistent: true, the session starts from the saved state but will not save changes when it ends. Set persistent: true on restored sessions if you want updates to be saved.
Sessions expire. Saved state has a retention period. If you haven’t used an environment in a long time, you may need to log in again.
Store your session IDs. Save the session id from persistent sessions to a database or config file so you can restore them later.

​
Security

Persistent sessions are designed with security in mind:
  • No credentials stored. We never store your login credentials (usernames, passwords). For browser sessions, only session cookies are preserved. For desktop sessions, a VM snapshot is saved.
  • Encrypted at rest. Saved state is encrypted before storage.
  • You control retention. Saved state remains available as long as you need it.
Encryption happens when the session terminates and state is persisted.

​
Complete Example

Here’s a full workflow that creates a persistent session, logs in, then demonstrates restoration: 
from tzafon import Computer
import json

client = Computer()

# === PART 1: Initial login ===
print("Creating persistent session and logging in...")

with client.create(kind="browser", persistent=True) as computer:
    computer.navigate("https://lingualeo.com/en")
    computer.wait(2)

    # Accept cookies if prompted
    computer.click(945, 645)
    computer.wait(1)

    # Click "Start Learning" / login button
    computer.click(1010, 35)
    computer.wait(1)

    # Click "I already have an account"
    computer.click(600, 600)
    computer.wait(1)

    # Enter credentials
    computer.click(600, 230)
    computer.type("your_email@example.com")

    computer.click(600, 300)
    computer.type("your_password")

    computer.click(600, 380)
    computer.wait(5)

    result = computer.screenshot()
    print(f"Logged in: {computer.get_screenshot_url(result)}")

    # Save for later
    session_id = computer.id
    print(f"Saved session: {session_id}")

# === PART 2: Restore and verify ===
print("\nRestoring session...")

with client.create(kind="browser", environment_id=session_id) as computer:
    computer.navigate("https://lingualeo.com/en")
    computer.wait(5)

    result = computer.screenshot()
    print(f"Restored (should be logged in): {computer.get_screenshot_url(result)}")

​
Use Cases

Log into a dashboard once, then run daily report extraction without re-authenticating.
Complete a complex onboarding flow once, then start future sessions from the logged-in state.
Set up test accounts with specific state (items in cart, preferences set), then restore that exact state for each test run.
Install tools, configure editors, and clone repos once on a desktop session, then restore the ready-to-use environment each time.
For processes that run over multiple days, persist state between runs to handle interruptions gracefully.

​
Next Steps

Session Lifecycle

Understand timeouts and billing

Actions Reference

Explore all available actions