teleport

NAME

teleport — transfer authentication state from a follower browser to the agent

SYNOPSIS

playwright-cli teleport --start=<regex> --return=<regex> [--timeout=<s>] [--runtime=<id>]
playwright-cli teleport --off
playwright-cli teleport --list

playwright-cli open <url> --teleport-start=<regex> --teleport-return=<regex> [--timeout=<s>]
playwright-cli goto <url> --teleport-start=<regex> --teleport-return=<regex> [--timeout=<s>]

DESCRIPTION

Remote agents can browse the web but cannot physically interact with login forms, CAPTCHAs, or multi-factor authentication prompts. Teleport solves this by delegating the authentication ceremony to a human on a follower browser, then beaming the resulting cookies, localStorage, and sessionStorage back to the leader's browser session.

The agent arms a teleport watcher with a start pattern (the URL that indicates an auth redirect has occurred) and a return pattern (the URL that indicates login is complete). When the leader tab navigates to a URL matching the start pattern, SLICC automatically opens that URL on a connected follower's browser where the human can complete authentication. Once the follower's URL matches the return pattern, all auth state is captured and injected into the leader tab, which then navigates to the post-login destination.

Teleport transfers cookies, localStorage, and sessionStorage. For cross-origin SSO flows (where the identity provider lives on a different domain than the application), teleport handles origin hydration automatically — it navigates the leader to the correct storage origin before replaying state, ensuring SPA auth caches are materialized on the right domain.

HOW IT WORKS

The teleport lifecycle proceeds through six phases:

1. Armed — The watcher is installed on a leader tab. A polling loop (1s interval) checks the leader tab's URL against the --start regex. Additionally, CDP Page events are monitored for navigation changes.
2. Triggered — The leader tab URL matches --start (e.g. the app redirected to an SSO provider). The watcher captures the leader's current cookies and storage, selects a follower runtime, and opens about:blank on the follower.
3. Follower setup — Leader cookies are injected into the follower via Network.setCookies. A storage init script is installed to replay localStorage and sessionStorage. The follower then navigates to the intercepted auth URL so the human sees the login flow mid-stream, not from the beginning.
4. Waiting for auth — The watcher polls the follower tab URL (1s interval). The human interacts with the login form, completes MFA, clicks through consent screens. The watcher transitions to "waiting for return" once the follower URL matches the start pattern (confirming it reached the auth provider).
5. Waiting for return — Polling continues until the follower URL matches the --return regex, indicating the auth flow completed and the app redirected back.
6. Capture and inject — A 2-second settle delay allows redirect chains to finalize. Cookies and storage are captured from the follower via CDP. The follower tab is closed. The leader tab receives the cookies via Network.setCookies, storage is replayed (either directly or via an init script for cross-origin cases), and the leader navigates to the post-auth landing URL.

During phases 2–6, subsequent playwright-cli commands targeting the same tab are automatically blocked until teleport completes or times out. This prevents the agent from interacting with a page that is mid-authentication.

FLAGS

• --start=<regex>

  JavaScript regex pattern matched against the leader tab URL. When matched, teleport triggers. Typically matches the identity provider's domain or login path (e.g. "login\\.okta\\.com", "accounts\\.google", "auth\\.example").

• --return=<regex>

  JavaScript regex pattern matched against the follower tab URL after auth. When matched, cookies and storage are captured. Typically matches the application's post-login path (e.g. "dashboard", "callback", "app\\.example\\.com").

• --timeout=<s>

  Maximum seconds to wait for the human to complete authentication. Defaults to 120 seconds. If exceeded, the watcher is disarmed, the follower tab is closed, and the command rejects with a timeout error.

• --runtime=<id>

  Explicit follower runtime ID to use for the auth handoff. If omitted, teleport automatically selects the best available follower from the tray.

• --off

  Disarm the active teleport watcher on the current tab. Stops URL polling and cleans up any pending state.

• --list

  List available follower runtimes that can receive teleport requests. Useful for verifying tray connectivity before arming.

INLINE TELEPORT

Teleport can be armed inline on navigation commands, combining the tab open/navigate with watcher setup in a single call. This is the most common usage pattern — the agent opens an authenticated app and arms teleport in case it gets redirected to login.

playwright-cli open https://app.example.com \
  --teleport-start="login\\.example" \
  --teleport-return="app\\.example\\.com/dashboard"

playwright-cli goto --tab=ID https://internal.corp.com \
  --teleport-start="sso\\.corp\\.com" \
  --teleport-return="internal\\.corp\\.com/home"

When using inline teleport, the watcher is armed immediately after navigation. If the page does not redirect to a URL matching --teleport-start, the watcher remains armed but dormant — it does not interfere with normal page interaction. The watcher is automatically cleaned up on timeout or when teleport --off is called.

Inline teleport flags are also supported on tab-new:

playwright-cli tab-new https://secure.example.com \
  --teleport-start="idp\\.example" \
  --teleport-return="secure\\.example\\.com/app" \
  --timeout=180

EXAMPLES

OAuth login to a SaaS app

# Open the app — if it redirects to Google OAuth, teleport handles it
playwright-cli open https://app.example.com \
  --teleport-start="accounts\\.google\\.com" \
  --teleport-return="app\\.example\\.com"

# Output after human completes login on follower:
# Teleported 14 cookie(s) (.example.com, .google.com) + 8 storage entries from follower-abc123 (navigated to https://app.example.com/dashboard)

Corporate SSO with Okta

# Arm watcher before navigating to an internal tool
playwright-cli teleport \
  --start="login\\.okta\\.com" \
  --return="internal\\.corp\\.com" \
  --timeout=180

# Then navigate — if SSO kicks in, teleport fires automatically
playwright-cli goto https://internal.corp.com/reports

Cookie-based legacy app

# Some apps use simple cookie auth with a /login page
playwright-cli open https://legacy.example.com/login \
  --teleport-start="legacy\\.example\\.com/login" \
  --teleport-return="legacy\\.example\\.com/home"

Targeting a specific follower

# List available followers
playwright-cli teleport --list

# Use a specific one (e.g. the one with access to VPN)
playwright-cli open https://vpn-only.internal.com \
  --teleport-start="auth\\.internal" \
  --teleport-return="vpn-only\\.internal" \
  --runtime=follower-laptop

Disarming a watcher

# Cancel an armed teleport if you no longer need it
playwright-cli teleport --off

REQUIREMENTS

• An active tray connection with at least one follower browser. Verify with host or playwright-cli teleport --list.
• The follower must be running on a device where a human can interact with the browser — teleport opens a real browser tab that requires physical input (typing credentials, clicking approve, completing MFA).
• The leader and follower must be connected via WebRTC data channel (signaled through the tray hub). Network connectivity between peers is required — TURN relay is used when direct connections fail.
• CDP (Chrome DevTools Protocol) access to both the leader and follower browser contexts. This is provided automatically by SLICC's browser integration.

NOTES

• Teleport blocks subsequent playwright-cli commands on the same tab while active. This is intentional — the page is in a transient auth state and interaction would be unreliable.
• Cross-origin storage hydration: when the auth provider sets storage on a different origin than the application, teleport navigates the leader to the storage origin first, replays the data, then navigates to the landing URL. This handles SPAs that cache tokens in localStorage on their own origin after an OAuth redirect.
• Leader cookies are pre-injected into the follower before navigating to the auth URL. This preserves any session state the app already had (e.g. CSRF tokens, partial session cookies) so the auth flow continues seamlessly rather than restarting.
• If the follower tab is closed manually before the return pattern matches, the teleport watcher will time out and reject.
• Multiple teleport watchers can be armed on different tabs simultaneously. Each watcher is keyed by its leader tab targetId.

SEE ALSO

tray, host, playwright-cli, rsync