diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index 92846ed..3f05f81 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -18,6 +18,7 @@ explains each one and how they fit together. | Actor | An AI user with instructions and knowledge that drives a real browser | | Checklist | Plain-language checks an actor verifies, each with evidence | | Interview | A structured study run with persona participants, ending in a report | +| Live session | An actor using your product in real time while you watch and steer it | | Automation | A graph of steps that runs checklists on a schedule or an event | | Comment | A pin a real visitor drops on your page through the feedback widget | | Insight | A notable observation surfaced from a run | @@ -42,6 +43,8 @@ Under the hood, an actor drives a real browser and works through your product the way a person would, observing the page, taking an action, observing the result, and repeating until the task is done. It can also read email sent to its own inbox, which is what makes signup and verification flows testable. +Actor inboxes, and actors that stay signed in between runs, come with the +Startup plan and above. ## Checklists @@ -66,6 +69,15 @@ You define sections and questions, the platform conducts the interview, and it produces a report summarizing what it learned. Interviews are useful for user research and feedback gathering at a scale that manual interviews cannot reach. +## Live sessions + +A **live session** puts you beside an actor while it works: the browser on one +side, the chat on the other, and the steps it takes underneath. Give it a task +or interview it in character, change direction mid-task, or take the browser +and drive it yourself. Sessions run in a cloud browser or, from the desktop +app, in a browser on your own Mac. See +**[Run a live session](/tutorials/live-sessions)**. + ## Workflows A **workflow** (an **automation** in the dashboard) chains steps into a single repeatable automation. Where a diff --git a/content/docs/integrations/desktop-app.mdx b/content/docs/integrations/desktop-app.mdx index d156e7a..dfe6304 100644 --- a/content/docs/integrations/desktop-app.mdx +++ b/content/docs/integrations/desktop-app.mdx @@ -1,23 +1,27 @@ --- title: "Desktop app" icon: "monitor" -description: "Run Stunt Double as a Mac app, and let actors browse with your computer's own Chrome, VPN and sign-ins." +description: "Run Stunt Double as a Mac app, let actors browse with your computer's own Chrome, VPN and sign-ins, and add local tools and models." --- # Desktop app The desktop app is Stunt Double in its own Mac window. It can also make your Mac a [device](/integrations/self-hosted-workers), so actors browse with this -computer's Chrome, including its VPN access and machine-credential sign-ins. +computer's Chrome, including its VPN access and machine-credential sign-ins, +and it runs [live sessions](/tutorials/live-sessions) in a browser on your +Mac, with MCP servers and models from this Mac. ## Before you start - **macOS.** macOS 10.15 or later, on Apple silicon or Intel. - **Chrome.** Google Chrome installed, if you want to use the Mac as a - device. + device. [Set up this Mac](#set-up-this-mac) can install a separate Chrome for + Testing for live sessions instead. - **Plan.** The app itself works on any plan. Using the Mac as a device needs - the Startup plan or above, with devices switched on by an owner or admin in - **Settings**, then **Devices**. + a paid plan, with devices switched on by an owner or admin in **Settings**, + then **Devices**. Testing private or internal addresses from it needs the + Startup plan or above. ## Install it @@ -26,7 +30,9 @@ computer's Chrome, including its VPN access and machine-credential sign-ins. 2. Open the download and drag Stunt Double into **Applications**. 3. Open the app and sign in with your Stunt Double account. -The app updates itself when a new version ships. +The app updates itself. It checks when it launches, when it wakes from sleep +and when you come back to it, so a Mac that is never quit still gets the +latest version. ## Use this Mac as a device @@ -38,16 +44,90 @@ The app updates itself when a new version ships. tab and, under **Where this actor's browser runs**, choose this Mac or **Any device in this workspace**. -The browser runs inside the app, not as a window on your desktop. Use the -device console to watch what an actor is doing, sign in to an internal site or -take control of the browser. Sign-ins you make there persist for later runs. - Setting up is remembered. When the app restarts, including after an update, the Mac reconnects by itself. Quitting the app closes its browser. To stop, click **Disable this device** in the console. A run already in progress stops with it. +A live session does not need this step: starting a session on **This Mac** +pairs the Mac in the background when it is not a device yet. + +### How the browser runs + +The device console lets you choose how the browser appears, under **How the +browser runs**: + +- **Inside the app** (the default). The browser has no window of its own. You + watch it in the device console and can take control when you need to. +- **Its own window.** A real Chrome window on your desktop. Slower to work + alongside, but the only way to answer a client certificate, Keychain or smart + card prompt. + +Both share one browser profile, so a sign-in done in either is available to +both. Sign-ins you make persist for later runs. You cannot switch while a task +is running. + +## Set up this Mac + +Live sessions on this Mac can use a few optional extras. Open them from the +app menu, **Stunt Double**, then **Set Up This Mac…**, or from **Packages and +models** in the device console. + +| Package | What it adds | +| ------------------ | ------------------------------------------------------------- | +| Chrome for Testing | A clean browser for sessions, kept apart from your own Chrome | +| Node | MCP servers that start with `npx` or `node` | +| uv | Python MCP servers that start with `uvx` or `uv` | +| Ollama | Running the actor on a model on this Mac | + +Each row says whether the package is already here and its size. Click +**Install** and the app asks you to confirm, naming the package, its size and +where it comes from, before it downloads anything. Every download is checked +against a published checksum before it is unpacked, and everything installs +into `~/.stuntdouble` in your home folder: nothing system-wide, and no +administrator password. A Node or uv you already have keeps working, and wins +over the one installed here. + +## Local models + +With Ollama installed and running, **Set Up This Mac** suggests models that +work well with actors: + +| Model | Size | Notes | +| -------------- | ------ | --------------------------------------- | +| `gemma3:4b` | 3.3 GB | Small, and reads screenshots | +| `qwen2.5vl:7b` | 6 GB | Reads screenshots; better at long tasks | +| `llama3.2` | 2 GB | Small and quick. Text only | +| `qwen2.5:7b` | 4.7 GB | Good at tools. Text only | + +Click **Install** on a model to download it. If you already run Ollama, the app +uses yours and the models you have pulled; otherwise it starts the one it +installed when it is needed, listening only on this Mac, and stops it when you +quit. + +When a live session's actor thinks with a model on this Mac, the model never +sees Stunt Double's credentials, and what it reads stays on your Mac. Only the +session's journey, captures and transcript are saved to your workspace, and the +end-of-session summary is built from those facts alone, without sending the +transcript to Stunt Double's model. + + + Choosing a local model for a session is in early access alongside live + sessions. A model that reads screenshots gives the actor a much better view of + the page than a text-only one. + + +## MCP servers on this Mac + +In a live session on this Mac, the actor can use MCP servers that run on your +Mac. They never run in Stunt Double's cloud. Add them in the app, or import +the ones you already use in Claude Desktop or Cursor from the session's +**Tools**. The app asks you to approve each server, showing the exact command, +before it starts, and editing a server's command switches it off until you +approve it again. See [Tools and sign-ins](/tutorials/live-sessions#tools-and-sign-ins) +for how they work in a session. + ## Troubleshooting **This Device asks you to install Google Chrome.** The device drives Chrome. @@ -74,3 +154,10 @@ allow Stunt Double to launch Google Chrome. **A run says the browser profile is in use.** Only one Chrome can use the device's profile at a time. Close any Chrome window still open on that profile, such as a sign-in window, and try again. + +**An install in Set Up This Mac fails.** Check the Mac is online and try again. +A failed install leaves any earlier version in place. + +**A Mac MCP server will not start.** Its command may need Node or uv. The +server's row in **Tools** says what is missing and links to **Set Up This +Mac**. diff --git a/content/docs/integrations/index.mdx b/content/docs/integrations/index.mdx index b792379..420455d 100644 --- a/content/docs/integrations/index.mdx +++ b/content/docs/integrations/index.mdx @@ -72,6 +72,11 @@ them. caption="Every integration is the same three steps. A finished step shows a tick; the next one to do is the first without." /> + + Slack and Linear connections depend on the workspace's plan: Free and Solo cannot connect + them, Hobby can connect one of the two, and Startup and above can connect both. + + A step that depends on the one before it stays greyed out until that step is done, so the next thing to do is always the first step without a tick. diff --git a/content/docs/integrations/self-hosted-workers.mdx b/content/docs/integrations/self-hosted-workers.mdx index 5acc952..6a69199 100644 --- a/content/docs/integrations/self-hosted-workers.mdx +++ b/content/docs/integrations/self-hosted-workers.mdx @@ -13,7 +13,10 @@ saved sign-ins. The app connects out to Stunt Double, so you open no inbound ports. For a full walkthrough, read -[Test a product behind your firewall](/tutorials/self-hosted-worker). +[Test a product behind your firewall](/tutorials/self-hosted-worker). To watch +and steer an actor on your own Mac in real time instead, start a +[live session](/tutorials/live-sessions) on **This Mac**: it pairs the Mac for +you in the background. ## What it does @@ -26,10 +29,10 @@ For a full walkthrough, read ## Before you start -- **Plan.** Devices are available on the Startup plan and above. On other plans, - **Settings**, then **Devices**, explains what they do and how to upgrade. - You see the same prompt when you point an actor at an address that only - works inside a network. +- **Plan.** Devices are available on every paid plan, for public sites. + Private and internal addresses (staging behind a VPN, an intranet, a local + dev server) need the Startup plan or above. Pointing an actor at one of those + on another plan shows what is needed and how to upgrade. - **Role.** A workspace owner or admin turns devices on. Once they are on, any member can set up their own Mac. - **A Mac.** macOS on Apple silicon or Intel, with Google Chrome installed, @@ -51,6 +54,11 @@ For a full walkthrough, read a run starts. - **A named device**, to always use that Mac. +The browser runs inside the app by default, and you watch it from the device +console. If a site asks for a client certificate, Keychain or a smart card, +switch **How the browser runs** to **Its own window** in the console (see the +[desktop app](/integrations/desktop-app#how-the-browser-runs)). + To check a device can reach a site before a run depends on it, enter the address under **Test connection** in **Settings**, then **Devices**. The test runs in the device's browser, so a pass means actors can reach that address. @@ -67,6 +75,10 @@ MCP server, the Figma plugin, the assistant, Slack, Linear or an interview. internal, or the address only works inside a network (a private IP range, for example), the run stops up front and asks you to choose a device for the actor. +- **Internal addresses need Startup.** Below the Startup plan, a run to a + private or internal address stops, on a device as well as in the cloud. +- **Cancelling frees the device.** Cancel a run from its report and the device + is free for the next one straight away. ## Move a Mac to another workspace @@ -106,8 +118,12 @@ and has outbound HTTPS to `app.stuntdouble.io`, then click **Reconnect**. **The console says "This device is no longer paired".** The device was removed from the workspace, or its key no longer works. Click **Pair again**. -**A run says devices need the Startup plan.** Devices are available on the -Startup plan and above. Upgrade from **Settings**, then **Billing**. +**A run says devices are not on your plan.** Devices are available on every +paid plan. Upgrade from **Settings**, then **Billing**. + +**A run says the address needs the Startup plan.** Private and internal +addresses need Startup or above, whether the actor runs on a device or in the +cloud. Upgrade from **Settings**, then **Billing**. **You need a custom deployment.** If the Mac app does not fit how your network works, for example you want the relay running in your own cloud, the diff --git a/content/docs/tutorials/index.mdx b/content/docs/tutorials/index.mdx index 4bd0486..2a9b19e 100644 --- a/content/docs/tutorials/index.mdx +++ b/content/docs/tutorials/index.mdx @@ -1,6 +1,6 @@ --- title: "Tutorials" -description: "Step-by-step guides for getting the most out of every part of Stunt Double: actors, checklists, interviews, workflows, Slack, devices, and the API." +description: "Step-by-step guides for getting the most out of every part of Stunt Double: actors, checklists, interviews, workflows, Slack, devices, live sessions, and the API." --- # Tutorials @@ -79,6 +79,13 @@ your usage grows. 'Connect the MCP server to Claude and drive actors, checklists, and interviews from a conversation.', href: '/tutorials/automate-with-mcp', }, + { + icon: 'actor', + title: '10. Run a live session', + description: + 'Watch an actor use your product in real time, steer it as it goes, take over the browser when you need to and keep what it finds.', + href: '/tutorials/live-sessions', + }, ]} /> diff --git a/content/docs/tutorials/live-sessions/index.mdx b/content/docs/tutorials/live-sessions/index.mdx new file mode 100644 index 0000000..a7ecf3d --- /dev/null +++ b/content/docs/tutorials/live-sessions/index.mdx @@ -0,0 +1,177 @@ +--- +title: "Run a live session" +icon: "actor" +description: "Watch an actor use your product in real time, steer it as it goes, take over the browser when you need to and keep what it finds." +--- + +# Run a live session + +A checklist run or an interview round goes off and comes back with a report. A +live session is the opposite: you sit beside the actor while it works. The +browser is on the left, the chat on the right, and underneath it the steps the +actor took and the captures it kept. Ask it to try something, watch what it +does, change the task halfway through, or take the browser and drive it +yourself. + + + Live sessions are in alpha and switched on per workspace. When they are on for + yours, **Live sessions** appears under **Discover** in each project's + navigation. + + +## Start a session + + + + +### Open Live sessions + +Open a project and choose **Live sessions** under **Discover**. The page lists +the project's sessions, newest first, so you can go back to any earlier one and +read what happened. + + + + +### Click New session + +The dialog asks only what cannot change once the session is running: + +- **Actor**: who uses the product. +- **Start on**: the address the browser opens first. +- **Session**: **Interview** or **Task** (see below). +- **Browser**: **This Mac** or **Cloud browser**. + +Replies, tools and sign-ins are all changed from inside the session. + + + + +### Click Start session + +The browser opens on the start address and the actor is ready for its first +message. + + + + +## Interview or task + +- **Interview** (the default): the actor stays in character and thinks aloud + while you moderate. Ask it what it expects a page to do, what it would click + next, or what would stop it signing up. This is a moderated usability + session without recruiting anyone. +- **Task**: the actor does what you ask and reports back. Use it to reproduce + a bug, walk a flow end to end, or check something quickly before a release. + +## Choose a browser + +- **Cloud browser** works from anywhere, on public sites. +- **This Mac** is offered when you are in the + [desktop app](/integrations/desktop-app) and your plan includes devices. The + actor drives a Chrome on your Mac, so it can open local dev servers, staging + behind your VPN and anything else this Mac can reach. When a session can run + on this Mac, it is the default. + +You do not need to set your Mac up as a device first. If it is not one yet, +starting the session pairs it for you in the background, and that pairing is +removed again when its last session ends. A Mac that already belongs to +someone else in the workspace, or to another workspace, is never moved: the +dialog says so and offers the cloud browser instead. + +## Steer the actor + +Type in the chat to give the actor a task or ask it a question. While it is +working, a new message is queued for when it finishes. Choose **Send now** to +steer the current task instead of waiting. + +Each step it takes appears in the journey under the browser, grouped by task, +so you can see exactly what it clicked, typed and read. + +### Replies + +The actor keeps replies short by default: the result first, no recap of the +task and no commentary on each click, since you can see the browser yourself. +Open **Replies** to change that from its next reply: + +- **Detail**: from a sentence to a thorough account with evidence. +- **Narration**: from results only to thinking aloud at every step. An + interview starts with more narration than a task. + +## Take control + +Click **Take control** in the header, or click or type in the browser +itself. If the actor is in the +middle of a step, it stops first. Now the browser is yours: sign in, fill a +form, dismiss a banner or get the page into the state you want. + +Click **Return control** when you are done. The actor is told you drove the +browser in the meantime, so its next step starts from the page as you left it. + +## Keep what it finds + +- **Findings** are recorded by the actor as it works, with a severity and the + screenshot that shows the problem. +- **Capture** saves a screenshot of the browser as it is now. It is off while + the actor is driving. +- **Notes** are your own, added from the captures tray. + +Captures stay with the session after it ends. + +## Tools and sign-ins + +Open **Tools** during a session to see what the actor can use beyond the +browser. + +- **Project and actor** MCP servers you have already connected in Stunt Double. +- **On this Mac**: MCP servers that run on your own Mac, in sessions using the + desktop app. Turn them on for the session, then import servers from Claude + Desktop or Cursor, or add them in the app. The app asks you to approve each + server, showing the exact command, before it ever runs, and the chat asks you + before each tool call. Switch on **Run read-only tools without asking** to + skip that question for tools their server marks read-only. + +What a tool returns is kept in the session's transcript, which everyone in the +workspace can read, so only turn on servers whose output you are happy to +share. + +**Browser sign-ins** (sessions on This Mac) controls where the browser keeps +its cookies and sign-ins: + +- **Per actor**: each actor keeps its own sign-ins, the way two real people + would. This is the default. +- **Shared in this workspace**: sign in once and every actor in the workspace + starts signed in. + +Sign-ins stay on your Mac, in a browser profile kept apart from your own +Chrome, so an actor never sees your personal sessions. The same section lists +the profiles stored on this Mac with their size, and can clear one. + +A Mac MCP server that starts with `npx` or `uvx` needs Node or uv. If it is +missing, the server's row links to [Set up this Mac](/integrations/desktop-app#set-up-this-mac), +which installs it. + +## End the session + +Click **End session** and confirm. The browser closes and the transcript, +journey and captures stay where they are. + +Once a session ends, a summary takes the browser's place: how long it ran, +the pages visited, the findings by severity and your notes, with a short +account of what happened and suggested next steps. + +A session left idle closes its browser on its own after a while. When that is +close, **Keep session open** appears in the header with the time it closes. + +## Who can see a session + +Only the person who started a session can chat with the actor or drive the +browser. Everyone else in the workspace can open it and follow along: the +journey, the captures and the transcript update live, and the browser pane +shows the latest screenshot. + +## Next steps + +- **[Set up the desktop app](/integrations/desktop-app)** to run sessions on your Mac +- **[Run an interview](/tutorials/running-an-interview)** across a whole panel of actors +- **[Write effective checklists](/tutorials/effective-checklists)** to keep checking what a session found diff --git a/content/docs/tutorials/meta.json b/content/docs/tutorials/meta.json index 70332ef..3836298 100644 --- a/content/docs/tutorials/meta.json +++ b/content/docs/tutorials/meta.json @@ -10,6 +10,7 @@ "...feedback-widget", "...slack-design-review", "...self-hosted-worker", - "...automate-with-mcp" + "...automate-with-mcp", + "...live-sessions" ] } diff --git a/content/docs/tutorials/reviewing-runs/index.mdx b/content/docs/tutorials/reviewing-runs/index.mdx index 751d036..d9511f4 100644 --- a/content/docs/tutorials/reviewing-runs/index.mdx +++ b/content/docs/tutorials/reviewing-runs/index.mdx @@ -33,6 +33,11 @@ A run report is organized into tabs: Start with Results to get the headline, then drop into Screenshots or the Recording when a result needs more context than the explanation gives you. +While a checklist run is still in progress, its report shows **Cancel run**, +so you can stop it from where you are watching. Cancelling a run on a +[device](/integrations/self-hosted-workers) frees that device for the next run +straight away. + ## What surfaces automatically as an insight Not everything worth knowing fits into a pass or fail. As actors work, diff --git a/content/docs/tutorials/self-hosted-worker/index.mdx b/content/docs/tutorials/self-hosted-worker/index.mdx index ba0bdc6..353eb2e 100644 --- a/content/docs/tutorials/self-hosted-worker/index.mdx +++ b/content/docs/tutorials/self-hosted-worker/index.mdx @@ -11,9 +11,10 @@ cloud browser can't reach it. A device is a Mac on your side of the firewall running the Stunt Double app, so actors browse from there without you opening anything up. - - Devices are available on the Startup plan and above. A workspace owner or admin switches - them on, then any member can set up their own Mac. + + Devices are on every paid plan, and testing private or internal addresses from one needs the + Startup plan or above. A workspace owner or admin switches devices on, then any member can set + up their own Mac. ## Turn devices on @@ -32,7 +33,8 @@ On other plans, this page explains what devices do and how to upgrade. The app dials out to Stunt Double rather than waiting for an inbound connection, so your firewall needs no changes. If your product sits behind a VPN portal or SSO, sign in once in the device console. The sign-in persists -for later runs. +for later runs. If the sign-in needs a client certificate, Keychain or a smart +card, switch **How the browser runs** to **Its own window** first. ## Choose where each actor's browser runs @@ -70,5 +72,6 @@ on it. ## Next steps - **[Devices reference and troubleshooting](/integrations/self-hosted-workers)** +- **[Run a live session](/tutorials/live-sessions)** to watch and steer an actor on your Mac - **[Automate multi-step workflows](/tutorials/building-workflows)** - **[Turn runs into insights](/tutorials/reviewing-runs)**