Portal

Turn any URL into a shareable live browser session. Viewers get a real browser running in a cloud VM — 10 minutes per session.

Install

CODEBLOCK0

Watch — AI clicks, scrolls, and narrates a guided demo.
Play — Viewer explores freely with AI guardrails blocking unwanted areas.

Quick Reference

Situation	Action
User says "make a portal" / "demo this site"	Start at Step 1 below
Public site (landing page, docs, marketing)

Skip login, go to Step 3 | | Authenticated site (dashboard, SaaS, admin) | save_login first (Step 2) | | Local file / localhost | Zip + base64, pass as ptl.entry.source | | Chrome extension | Zip extension + set entry.url for test site | | User wants guided demo | Watch mode → create_script | | User wants free exploration | Play mode → create_script with play mode | | User wants to record themselves | record_demo → user records in hosted browser | | User wants to pick blocked elements | pick_selectors → user clicks in hosted browser | | Portal is "provisioning" | make_portal auto-polls — just wait for the result | | Session is pending | Poll get_session — it blocks 30s server-side, keep calling | | Need session replays | get_portal_sessions → returns conversation logs + recording URLs | | User needs more credits | buy_credits → opens Stripe checkout |

Sending URLs to the User

When any tool returns a URL the user needs to open (verification_url, hosted_url,
portal link, checkout URL), you MUST send it to the user in the current chat.
Do NOT attempt to run shell commands like open or xdg-open — the user is on a
messaging channel (WhatsApp, Telegram, etc), not a local desktop.

Just include the URL in your reply. The user will tap it on their device.

Workflow

Follow these steps in order. Never skip the review step (Step 4).

Step 1 — Authenticate

Call portal_status. If not authenticated, call portal_login.

Returns verification_url and device_code. Send the verification URL to the user
in the chat so they can open it and sign in.

Poll portal_login_check with the device_code every 5 seconds until approved.

New users get 3 creation credits + 10 view credits.

Step 2 — Classify the Site

Ask the user if you're unsure whether the site needs login.

Public site → skip to Step 3.

Needs login → capture auth state:

CODEBLOCK1

Call save_login with the above. Response includes hosted_url — send it to the user
so they can open the hosted browser and log in.

Poll get_session until status is ready. Do NOT ask the user if they're done — the tool tells you. When ready, grab saved_state_id.

Local file → zip the project (exclude node_modules, .git, dist), base64 encode.
Pass contents as ptl.entry.source with entry.type: "local_file".

Step 3 — Generate Content

Offer the user 4 options if they don't specify:

1. 1. Watch — AI script (default for landing pages)
2. Watch — Record yourself
3. Play — AI selectors (beta)
4. Play — Pick elements yourself

Watch — AI script (most common):

CODEBLOCK2

Use max_pages: 3 to get multi-page demos (homepage + pricing + features). Without it, demos stay on the homepage only.

Writing great goals:

• - Be specific: "Navigate to pricing page" > "Show pricing"
• Ask for navigation: "Click to the features page" produces click actions, not just scrolls
• Ask for social proof: "End with customer logos or metrics" pulls real stats
• Ask for variety: "Include interactive elements like tabs or accordions"

Call create_script. It auto-polls internally and returns the complete draft directly — no need to call get_script.

Watch — Record yourself: Call record_demo. Send the hosted_url to the user so they can record in the hosted browser.

Play — AI selectors: Call create_script with mode: "play".

Play — User picks: Call pick_selectors. Send the hosted_url to the user so they can click elements in the hosted browser.

Step 4 — Review with User (MANDATORY)

Never skip this step. Show the user everything from the draft:

Watch mode:

• - Each scene with narration text and actions
• Example Q&A pairs — ask if answers are accurate
• AI greeting and knowledge summary

Play mode:

• - Blocked selectors and allowed URLs
• AI greeting and knowledge

Ask: "What do you want to call this? Look good to go?"

Slugify the name for the URL (lowercase, hyphens, no spaces).

Step 5 — Deploy

Call make_portal with the full PTL spec. Costs 1 creation credit.

It auto-polls internally until the portal is ready — the result includes the final portal URL. Send it to the user.

Step 6 — Post-Deploy (Offer These)

• - Add CTA button: Call configure_portal with cta_text and INLINECODE43
• Get embed snippet: Call configure_embed with INLINECODE45
• View session replays: Call INLINECODE46
• Debug issues: Call INLINECODE47

PTL Spec (Minimal)

The ptl parameter to make_portal MUST be a JSON object (not a string). Do NOT JSON.stringify it.

Play mode:
CODEBLOCK3

Watch mode:
CODEBLOCK4

Supported action types:

Action	Use for	Required fields
INLINECODE50	Navigate to a section by heading	INLINECODE51, INLINECODE52
INLINECODE53

Generic scroll | selector: "body" |
| click | Navigate pages, open tabs/accordions | selector, inner_text |
| wait | Pause for emphasis (1500-3000ms) | ms |
| type | Type into form inputs | selector, text |
| keypress | Keyboard shortcuts | selector, key |

Scenes can have multiple actions (up to 20 per scene). A good scene flows: scroll → wait → click.

Server auto-fills version, region, entry.type. No need to call normalize_ptl or validate_ptl before make_portal — validation is built in.

Improving Script Quality

When reviewing drafts from create_script, improve them before deploying:

1. 1. Add click actions for navigation: If the draft only has scroll_to_element actions, add click actions to navigate between pages (pricing, features, docs).
2. Add wait actions for pacing: Insert { "type": "wait", "ms": 2000 } between actions for natural pacing and emphasis.
3. Use multiple actions per scene: Don't limit scenes to 1 action — scroll to a section, wait, then click or highlight another element.
4. Include social proof: End with a scene that scrolls to customer logos, testimonials, or metrics.
5. Keep narrations concise: Under 2 sentences per scene — the viewer is watching, not reading.
6. Always include inner_text: On every click and scroll_to_element action — it's the fallback when CSS selectors break on dynamic pages.

Cursor Movement

Portal demos show a real cursor moving on screen. The cursor automatically:

• - Moves to the target element before each action
• Follows scrolls smoothly
• Clicks precisely on elements with visual feedback

For best results:

• - Use scroll_to_element with specific inner_text (not just body) so the cursor targets a visible heading
• Place click actions on prominent buttons/links with clear INLINECODE83
• Use wait between actions so viewers can see the cursor position before the next move

Rules

• - Do NOT use the built-in canvas tool for portal creation — use the portal* tools from this plugin
• Never guess CSS selectors — only use what create_script or pick_selectors returns
• Never navigate authenticated sites autonomously — auth sites get single-page CDP grab only
• Always show draft and get user confirmation before INLINECODE87
• Keep polling get_session — it blocks 30s server-side. Do NOT ask user if they're done
• Pass inner_text on all click and scrollto_element actions — it's the fallback when selectors fail on dynamic pages
• Never create a second portal while one is provisioning — poll get_portal instead
• Send URLs to the user in the chat — do NOT run shell commands to open URLs. The user is on a messaging channel and will tap the link themselves
• Request multi-page demos — always pass max_pages: 3 (or higher) in create_script to get richer navigation beyond the homepage