Read https://demoready.ai/docs.md and set up DemoReady for me. DemoReady for AI agents
DemoReady turns your AI coding agent into a demo director. Your agent (Claude Code, Codex, Cursor, or any MCP client whose model can read screenshots) opens your app, decides every click, and narrates as it goes. DemoReady performs each step with a smooth cursor, captions, highlights and voice-over, and records a polished 1080p MP4 into your library. It also works with apps running on your own computer (localhost).
AI agents: this page is written so you can set DemoReady up for your user. Follow Setup for AI agents. The only thing the user does by hand is enter their API key, in their own terminal.
- Plain-text version of this page: https://demoready.ai/docs.md
- Connector package: demoready-mcp on npm
Setup for AI agents #
Do these steps for the user, in order.
- Check Node.js. Run
node --version. It must be 22 or newer. If it isn't, ask the user to install Node 22+ from https://nodejs.org and stop here. - Add the DemoReady MCP server to the client you are running in, using the exact command or config for that client in Add DemoReady to your agent. No API key goes into the config.
Have the user sign in. Ask the user to run this in their own terminal (not through you), so their key is never shown in the chat:
npx -y demoready-mcp loginIt asks for their API key without showing it, checks it, and saves it to
~/.demoready/credentials.json(readable only by them). They create a key at https://demoready.ai/app/settings/api. Recording needs a DemoReady plan (MCP, MCP Plus, Pro or Studio) or a single-demo credit.Never ask the user to paste their API key into the chat, and never write a key into a file yourself.
- Reload. Tell the user to restart the client (or reload its MCP servers) so the
demoreadytools appear. - Verify. Run
npx -y demoready-mcp status. It should printSigned in as … (plan). After the reload, thedemoreadyserver should list tools such asdemo_openanddemo_record_start.
Then record a first demo. See Directing a demo.
Add DemoReady to your agent #
All clients run the same connector, npx -y demoready-mcp. It downloads on first use and needs no other install.
Claude Code #
claude mcp add --scope user demoready -- npx -y demoready-mcpCheck with claude mcp list.
Codex #
codex mcp add demoready -- npx -y demoready-mcpThen open ~/.codex/config.toml and add the two timeout lines to the demoready entry. Recording and encoding can take a few minutes, longer than Codex waits by default. The entry should look like this (you can also paste it in directly instead of running the command):
[mcp_servers.demoready]
command = "npx"
args = ["-y", "demoready-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 600Check with codex mcp list.
Cursor #
Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"demoready": {
"command": "npx",
"args": ["-y", "demoready-mcp"]
}
}
}Claude Desktop #
Add the same mcpServers entry as Cursor to claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Then quit and reopen Claude Desktop.
Windsurf #
Add the same mcpServers entry as Cursor to ~/.codeium/windsurf/mcp_config.json.
VS Code (GitHub Copilot agent mode) #
Add to .vscode/mcp.json in the workspace (or run MCP: Add Server from the command palette):
{
"servers": {
"demoready": {
"type": "stdio",
"command": "npx",
"args": ["-y", "demoready-mcp"]
}
}
}Any other MCP client #
Run it as a stdio server: command npx, arguments -y demoready-mcp. On Windows, if the client can't find npx, use command cmd with arguments /c npx -y demoready-mcp.
Passing the key as an environment variable #
Instead of demoready-mcp login, you can set DEMOREADY_API_KEY in the MCP server's environment (for example claude mcp add --scope user demoready -e DEMOREADY_API_KEY=dr_live_… -- npx -y demoready-mcp). It takes priority over the saved login. This suits CI and shared machines, but it stores the key in the client's config file.
No install (public apps only) #
Clients that support remote MCP servers can connect straight to https://demoready.ai/mcp with the header Authorization: Bearer dr_live_…. This records public URLs only; it can't reach localhost.
claude mcp add --scope user --transport http demoready https://demoready.ai/mcp --header "Authorization: Bearer dr_live_YOUR_KEY"Signing in #
| Command | What it does |
|---|---|
npx -y demoready-mcp login | Asks for an API key (hidden), checks it with DemoReady and saves it to ~/.demoready/credentials.json with owner-only permissions. |
npx -y demoready-mcp status | Shows which account and plan the connector uses, and where the key comes from. |
npx -y demoready-mcp logout | Deletes the saved key. Revoke the key itself under Settings → API & MCP. |
Create and revoke keys at https://demoready.ai/app/settings/api. Each key acts as your account: demos it records count toward your plan.
Recording apps on your computer #
Use a local URL like any other: http://localhost:3000, http://127.0.0.1:5173, http://myapp.test, *.localhost, *.local or a private IP. When the agent opens one, the connector makes an encrypted, outbound-only connection to DemoReady and shares that address with the recording browser.
If the app calls an API on another local address, the agent lists it in demo_open's local_hosts, for example local_hosts: ["localhost:8000"]. Otherwise those calls fail.
How it stays safe:
- Only the addresses the agent opened are shared. The connector refuses any other request (another port, another device on your network) on your machine, and logs it.
- Only your recordings can use the connection. It's signed in with your key and routed only to your own sessions.
- Only until the recording ends. Sharing stops when the demo finishes or is discarded, and whenever the connector exits.
- Nothing gets a public URL, and no port is opened on your computer.
- The connector never follows redirects itself; the recording browser re-checks where they lead.
While sharing, the connector logs a line such as [demoready] sharing http://localhost:3000 with your DemoReady recording (only this address, until the recording ends).
Limits: 25 MB per response and 120 seconds per request. Streamed responses (Server-Sent Events, token-by-token AI answers) arrive all at once instead of streaming. Web-app demos can't reach localhost; this works over MCP only.
Directing a demo #
These are the same instructions the DemoReady MCP server gives your agent:
DemoReady records polished product-demo videos of web apps. You are the director: you decide every step, DemoReady performs it with smooth cursor motion, highlights and captions, and records 1080p video.
Look: demo_open takes a style for captions, callouts and title cards (studio, clean, bold, aurora, terminal, editorial). If the user hasn't said which, call list_styles to see previews, describe the options (or share the preview links), and let them choose.
Workflow:
- demo_open(url): opens a browser (off camera) and returns a screenshot with numbered elements. Explore, log in, or set up data with demo_act; nothing is recorded yet. Return to the starting screen when ready.
- demo_record_start(title, subtitle): the intro card plays and recording starts.
- For each scene: demo_scene(title, caption) puts a viewer caption on screen, then use demo_act for that scene's clicks and typing. Every demo_act returns a fresh screenshot.
- demo_finish(headline, cta): outro card, encode, returns the MP4 path.
Local apps (localhost, 127.0.0.1, *.test): these work when DemoReady was added through its connector (npx -y demoready-mcp), which securely shares only the address you open. If the app calls other local addresses (an API on another port), list them in demo_open's local_hosts.
Prefer demo_move for showing content (a row of steps, features, pricing, a call to action): one call, smooth motion paced to your narration, instead of many demo_act calls.
The recording is paused while you think, so take the time you need: viewers only see actions. Keep demos tight: 3-6 scenes, a few purposeful actions each, no trial and error on camera (explore before demo_record_start if unsure). Use callouts sparingly for the key moment of a scene. Everything typed is visible in the video.
Narration: pass
narrationto demo_record_start, demo_scene and demo_finish to have a voice read that line at that exact point in the video. DemoReady's built-in voice speaks it (no extra key needed) and mixes it in at demo_finish. Write it as speech, not as caption text: spell numbers out ("twenty five percent", "eight hundred sixty four thousand"), keep a scene's line to roughly 2.3 words per second of what that scene will actually take, and let the caption carry the label while the narration carries the meaning. A scene with nonarrationis simply silent, so narrate all of a demo or none of it.
Tools #
| Tool | What it does |
|---|---|
demo_open | Opens the app off camera and returns a screenshot with numbered elements. Takes url, optional style (overlay look, one of 11; see list_styles), pace, brand_color, camera_zoom, showcase (framing and push-in camera, on by default; false for a plain recording), and local_hosts for extra local addresses. |
demo_export | Another format of a finished demo: vertical (9:16), square (1:1), gif, srt/vtt subtitles, a txt transcript, chapters, or a step-by-step help article (guide as HTML, guide_pdf as PDF) with a highlighted screenshot of every step. Returns a download link; subtitles and transcripts also come back as text. |
get_saved_login | The test login saved for an app in Settings → Sites, if the user allowed agents to use it. For signing in off camera. |
list_styles | Previews of the 11 looks (captions, callouts, spotlight, title cards) as an image and links, so the agent can help the user choose a style for demo_open. |
demo_act | One polished action: click, type, select, press, hover, scroll, spotlight, wait, navigate. Returns a fresh screenshot. Off camera until recording starts, so it's also for logging in and seeding data. |
demo_move | A ready-made move in one call (walk_items, tour_section, highlight, point_cta, fill_form), paced to your narration. |
demo_observe | A fresh screenshot without acting. |
demo_record_start | Intro card; recording starts. Uses one demo from the plan. Optional narration, voice and language (en, es, fr, it, pt, hi): write captions and narration in that language and pick a voice that speaks it. |
demo_scene | Puts the next scene's caption on screen, with optional narration. |
demo_finish | Outro card, voice-over mix and encode. The video lands in the library. |
demo_close | Discards a session without saving. |
list_demos, get_demo | The user's library. |
Example prompts #
- Use demoready to record a 3-scene demo of http://localhost:3000 showing how to create a project and invite a teammate. Log in off camera with demo@acme.test / demo first.
- Record a narrated demo of our pricing page at https://acme.com/pricing: walk through the plans, then point to Start free trial.
- Record the new onboarding flow on localhost:5173. The API runs on localhost:8000.
Ask for a look by name ("…in the Terminal style"), or ask the agent to show you the options; it calls list_styles.
Tips: use test accounts and demo data (everything typed appears in the video, and actions really happen in the app); keep it to 3–6 scenes; explore before recording starts.
Record every pull request (GitHub Action) #
The DemoReady GitHub Action records a demo video of each pull request's preview deployment (Vercel, Netlify, Render, or your own) and posts it as a comment on the pull request: thumbnail, watch link, MP4 and the scenes that played. When the preview redeploys, the same comment updates.
Two ways to record:
- Replay a demo (
from-demo): performs a demo you already made, in the web app or with your agent, again on the preview. The same steps every time. Works on every plan, including MCP. - Describe a new one (
story): DemoReady's AI records whatever you describe, e.g. "Sign up and create a first project". Needs Pro, Studio or a demo credit.
Each recording uses one demo from your plan. If it fails before producing a video (for example, the preview was down), you get the demo back.
Set it up #
- Make the demo to replay (skip if you use
story). Record it once against production or staging, in the web app or with your agent. Its ID is the last part of its address:https://demoready.ai/app/demos/<id>. - Create an API key at https://demoready.ai/app/settings/api.
Save the key as a repository secret named
DEMOREADY_API_KEY: in GitHub, Settings → Secrets and variables → Actions → New repository secret. Or, from the repository folder in your own terminal:gh secret set DEMOREADY_API_KEY- Add the workflow below as
.github/workflows/demoready.yml, setfrom-demo(orstory), and commit it. - Open a pull request. When its preview is deployed, the demo comment appears within a few minutes.
AI agents: you can do steps 4 and 5 for the user. Never handle the API key: the user saves the secret themselves (step 3).
Vercel, Netlify and other previews that report a deployment #
name: PR demo
on: deployment_status
permissions:
pull-requests: write
jobs:
demo:
if: github.event.deployment_status.state == 'success' && github.event.deployment.environment != 'Production'
runs-on: ubuntu-latest
steps:
- uses: Sundrylab/demoready-action@v1
with:
api-key: ${{ secrets.DEMOREADY_API_KEY }}
url: ${{ github.event.deployment_status.environment_url }}
from-demo: a1b2c3d4Previews you build in the workflow #
name: PR demo
on: pull_request
permissions:
pull-requests: write
jobs:
demo:
runs-on: ubuntu-latest
steps:
# …deploy your preview first, then pass its address:
- uses: Sundrylab/demoready-action@v1
with:
api-key: ${{ secrets.DEMOREADY_API_KEY }}
url: https://pr-${{ github.event.number }}.preview.example.com
story: "Sign up, create a first project and invite a teammate"
style: bold
music: upbeatInputs and outputs #
| Input | Default | What it does |
|---|---|---|
api-key | required | Your DemoReady API key, from a secret |
url | required | The preview deployment to record |
from-demo | ID of a demo to replay on the preview | |
story | What DemoReady's AI should show (instead of from-demo) | |
style | the demo's own | studio, clean, bold, aurora, terminal, editorial, neon, brutalist, playful, cinema, slate |
voice | the demo's own | Narration voice, e.g. af_heart, bm_george |
music | the demo's own | calm, upbeat, tech, warm, lofi, corporate, cinematic, house, playful, ambient, synthwave, jazz |
comment | true | Post and update the pull request comment |
fail-on-error | false | Fail the workflow step when the demo can't be recorded |
timeout-minutes | 20 | How long to wait for the video |
Outputs: demo-id, share-url, video-url, status (done or failed), for use in later steps.
Good to know #
- The preview must be reachable from the internet. If it needs a login, save a test login for the preview's address in Settings → Saved sites, or replay a demo that signs in off camera.
- Previews behind Vercel Deployment Protection need a protection bypass or the protection turned off for previews.
- PR videos are shared by link so the comment can show them. Turn sharing off for any demo in DemoReady.
- Demos made on your computer (
localhost) can be replayed on a preview too: the steps follow the demo to the preview's address.
Plans #
| Plan | Price | Demos | Where | Scenes per demo |
|---|---|---|---|---|
| MCP | $4.99/month | 10 demos a month | MCP only | up to 15 |
| MCP Plus | $9.99/month | 30 demos a month | MCP only | up to 15 |
| Pro | $29/month | 30 demos a month | MCP and the web app | up to 8 |
| Studio | $99/month | 150 demos a month | MCP and the web app | up to 15 |
| Single demo | $4 once | 1 demo | MCP or the web app | up to 8 |
| Free demo | $0, once per account | 1 demo, watermarked | the web app | up to 4 |
A demo is used when recording starts (demo_record_start). Exploring and closing a session without recording is free. Plans and billing: https://demoready.ai/app/settings/billing.
Troubleshooting #
| Problem | Fix |
|---|---|
UNABLE_TO_GET_ISSUER_CERT_LOCALLY or SELF_SIGNED_CERT_IN_CHAIN (often on company laptops) | Your network inspects HTTPS with a certificate your browser trusts but Node doesn't. On macOS, export it: security find-certificate -a -p /Library/Keychains/System.keychain > ~/.demoready-ca.pem, then set NODE_EXTRA_CA_CERTS=~/.demoready-ca.pem in your shell and in the env of the DemoReady MCP server config. Node 22.19+ picks up the system certificates automatically with connector 1.1.3+. |
| "DemoReady isn't signed in yet" | Run npx -y demoready-mcp login in your terminal, then restart the client. |
| "didn't accept that key" / tunnel refused | The key was revoked or mistyped. Create a new one and run login again. |
The demoready tools don't appear | Check node --version is 22+, restart the client, and check its MCP logs. The connector caches the tool list in ~/.demoready/tools.json. |
| Codex says a tool timed out, but the video appears later | Add tool_timeout_sec = 600 to the Codex entry (see Codex). |
| "… is on your computer, which DemoReady can't reach directly" | DemoReady was added with the no-install HTTP address. Switch to the connector (npx -y demoready-mcp). |
| The local page loads but data is missing | The app calls an API on another port. Ask the agent to add it to local_hosts. |
| GitHub Action: no comment on the pull request | Give the workflow permissions: pull-requests: write, and check the step's log for the reason. Pull requests from forks don't receive secrets. |
| GitHub Action: "Demo not found" | from-demo must be the ID of a demo in the same DemoReady account as the API key. |
| "You've used all … demos" or "Buy a single demo" | Your plan's demos for the month are used up, or your account has no plan yet. Upgrade or buy a single demo at https://demoready.ai/app/settings/billing. |
Still stuck? Email hello@sundrylab.ai.