SPHYNX
esc
  • Loading
Open console

Guides

Live view

Watch a session as it runs, in a browser tab or inside your own page.

At the end you are watching a session's browser while your code or an agent drives it. You need an API key and a running session.

Get the URL

Creating a session returns a live_view_url. Keep it along with the session ID.

curl
CREATED=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_url": "https://example.com"}')

SESSION=$(echo "$CREATED" | jq -r .id)
echo "$CREATED" | jq -r .live_view_url
Output
https://api.example/v1/sessions/sess_9f2c.../view?token=...

Open it

Open the URL in a browser. It carries its own token, so it needs no API key and no header. Drive the session from another terminal and the view follows.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/navigate" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

Embed it

Put the URL in an iframe to show the session inside your own page.

The stream has the shape of the session's viewport, scaled down to fit 1280×800: a 1920×937 viewport arrives as 1280×625 frames, about 2:1. The live view page fits the frame inside its window, so an iframe of another shape shows bars beside or above it.

When the page is embedded it posts the pixel size of the frame it is drawing to its parent window, on the first frame and again whenever the size changes.

The message
{ "type": "sphynx:frame-size", "width": 1280, "height": 625 }

Start the iframe at 2 / 1 and shape it from the message.

HTML
<iframe
  id="live"
  src="LIVE_VIEW_URL"
  style="width: 100%; aspect-ratio: 2 / 1; border: 0"
></iframe>
<script>
  const live = document.getElementById("live");
  window.addEventListener("message", (event) => {
    const { type, width, height } = event.data ?? {};
    if (event.source !== live.contentWindow || type !== "sphynx:frame-size") return;
    if (width > 0 && height > 0) live.style.aspectRatio = `${width} / ${height}`;
  });
</script>

A change of the viewport's size reaches the stream about 0.15 s late: a frame of another size is held until the browser confirms it. The capture of a full-page or element screenshot is such a frame: it is not shown and sends no message.

Mint a fresh URL

The token in the URL is valid for token_expires_in_seconds, 1800 when issued, and can be reused until then. It works for the live view only, not for cdp_url. The URL is not on GET /v1/sessions/{id}. For a new one, call POST/v1/sessions/{id}/tokens on the running session.

Do this on your server and hand only the live_view_url to the page. The API key never has to reach a browser.

curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/tokens" \
  -H "Authorization: Bearer $SPHYNX_API_KEY"
200
{
  "cdp_url": "wss://api.example/v1/sessions/sess_9f2c.../cdp?token=...",
  "live_view_url": "https://api.example/v1/sessions/sess_9f2c.../view?token=...",
  "token_expires_in_seconds": 1800
}

What watching does not do

  • It is view only in v0. A viewer cannot click or type.
  • It does not keep the session alive. Watching does not reset the idle clock, so a session nobody drives still ends after idle_timeout_seconds.
  • It does not need the API key, so anyone who has the URL can watch until the token expires. Share it with that in mind.
  • At most 5 viewers can watch one session at a time. One more is refused with 429 connection_limit.

Watch an agent run

Starting an agent run returns a live_view_url for the run's session. Open it next to the run's event stream to see each step as it happens. The console shows the live view of each running session.

What can go wrong

HTTPCodeWhen
403invalid_tokenThe token in the URL is bad or expired. Mint a new URL
404session_not_foundNo such session for this key, when minting
410session_closedThe session has ended, so there is nothing to watch
429connection_limitThe session already has 5 viewers. Close one, then open the URL again

Next

  • Sessions: the session object and the tokens call.
  • Authentication: how session tokens differ from the API key.
  • Agent runs: give a task to an agent and watch it work.