Skip to main content
The GSD Browser live viewer gives you — and any collaborator — a real-time window into exactly what the agent’s browser is doing. You can watch passively, pause and step through actions one at a time, take manual control of the keyboard and mouse, annotate key moments, and hand control back to the agent without breaking the session. Every action the agent takes is narrated in a scrollable history panel alongside the live frame.

​
Start the Viewer

1

Begin a named session

Use --session so every command in the flow attaches to the same browser context, viewer, and history.
gsd-browser --session demo navigate https://example.com
2

Open the viewer

gsd-browser --session demo view
GSD Browser prints a localhost URL (e.g. http://127.0.0.1:7878/viewer?token=...) and opens it in your default browser. The URL includes a one-time security token — share it only with collaborators who should have access.If you need the URL without auto-opening (for example, to pass it to another tool):
VIEW_URL=$(gsd-browser --session demo view --print-only | tail -1)
echo "$VIEW_URL"
3

Set a goal banner (optional)

Display a visible goal message so collaborators understand what the agent is doing:
gsd-browser --session demo goal "Complete the checkout flow"
Clear it when the step is done:
gsd-browser --session demo goal --clear
4

Drive actions normally

Keep issuing CLI or MCP commands. The viewer reflects every action in real time — clicks, typing, navigation, and failures all appear with target rings, cursor animations, and narration entries.
gsd-browser --session demo snapshot
gsd-browser --session demo click-ref @v1:e3
gsd-browser --session demo fill-ref @v1:e1 "user@example.com"
gsd-browser --session demo act --intent submit_form
5

Stop the session when done

Stop the daemon when no further browser work is needed:
gsd-browser --session demo daemon stop

​
Viewer Controls

The viewer exposes controls directly in the browser UI. You can also use keyboard shortcuts.
ControlKeyboard ShortcutEffect
PauseSpaceBlocks the agent before its next narrated action
ResumeSpaceAllows agent actions to continue
Step→ (Right Arrow)Allows exactly one action, then returns to paused
AbortEscAborts the next queued action
Refs overlayRShows or hides bounding boxes and labels for interactive elements

​
Human Takeover

Take full manual control of the browser without terminating the session:
1

Click Take Control in the viewer UI

The agent pauses immediately. The session remains live — cookies, auth state, and page context are all preserved.
2

Interact manually

Use your mouse and keyboard in the viewer to click, type, scroll, or navigate. All manual actions are captured in the narration history.
3

Click Resume Agent to hand back

The agent picks up from the exact page state you left it in. It re-snapshots automatically before its next action.
In MCP mode, use browser_takeover to pause and browser_release_control to hand back programmatically.

​
Annotation Tools

Mark important moments directly in the viewer so they appear in the narration log and any exported evidence bundle.

Draw overlays

Highlight regions of the page with freehand drawing to call attention to specific elements.

Add notes

Attach text annotations to the current frame — these become timestamped entries in the narration history.

Mark elements for the agent

Flag elements in the viewer so the agent’s next snapshot includes a prioritized hint for that region.

Narration history

Every annotation streams to the MCP server and appears in the narration log. Retrieve the full log at any time.
Request an annotation from the CLI — a prompt appears in the viewer for the human collaborator to fill in: 
gsd-browser --session demo annotation-request "Please confirm the price shown here"

​
Review History

Open a history-focused view without issuing new browser actions: 
gsd-browser --session demo view --history
History items show pending, success, and failure states. Hover an entry in the viewer to preview the captured frame around that action.

​
Fast Agent Runs

For agent-only runs where no human needs the cursor lead-in animation, use --no-narration-delay. The narration history is still recorded — only the lead-time sleep is skipped. 
gsd-browser --session demo --no-narration-delay navigate https://example.com
gsd-browser --session demo --no-narration-delay click-ref @v1:e2

​
When to Use the Live Viewer

Compliance review

Let a compliance officer watch the agent complete a regulated workflow and annotate the key attestation steps in real time.

Debugging

Pause and step through a failing flow action-by-action to pinpoint exactly where the agent goes wrong.

Training data collection

Record the viewer session — including manual takeovers and annotations — as a rich, labeled training dataset.

User acceptance testing

Let a QA engineer watch the agent run a user story and intervene at any point to verify or correct behavior.
Recordings started during an active viewer session produce the highest-quality evidence bundles because they capture both agent actions and human annotations in a single enriched timeline. Start a recording with gsd-browser --session demo record-start --name my-flow before your viewer session for the richest output.