@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/bring-your-own-machine.mdx

@@ -1,112 +1,90 @@
 ---
-title: "Run on Your Own Machine"
-sidebarTitle: "Your Own Machine"
-description: "Run the TestDriver runner on a laptop, desktop, or VM you control and drive it from your tests."
+title: "Run tests on your own machine"
+sidebarTitle: "Your own machine"
+description: "Run the TestDriver runner on a laptop, desktop, or VM you control, and point your tests at it."
 icon: "display"
 ---
 
-TestDriver normally provisions a cloud sandbox for you. You can instead run the **runner** on a machine you own: a developer laptop, an office Mac, a lab Windows box, or a VM in your own data center. Your tests then drive that machine instead of a cloud sandbox.
+import { EnterpriseBadge, EnterpriseCta } from '/snippets/enterprise.mdx';
 
-This is useful when the machine under test cannot be replicated in the cloud: specific hardware, a licensed desktop application, a device plugged into USB, or an app that only reaches an internal network.
+Run your tests on a machine you control instead of a cloud sandbox. It can be a laptop, a lab machine, or a VM in your own data center.
 
-```mermaid
-graph LR
-    A[Your Test] --> B[TestDriver API]
-    B --> C[Ably Channel]
-    C --> D[Runner on your machine]
-    D --> C
-```
+Use it when the cloud can't reproduce the machine under test, for example:
 
-<Note>
-  The runner only makes **outbound** connections, to the TestDriver API and to Ably. You do not need to open an inbound port or expose the machine to the internet.
-</Note>
+- Specific hardware, or a device plugged in over USB.
+- A licensed desktop app.
+- An app that only reaches your internal network.
 
-## Choose your path
+The machine runs the TestDriver **runner**. Your test sends commands to it through the TestDriver API.
 
-| Your machine | Use |
-|---|---|
-| Windows EC2 instance in your AWS account | [AWS Setup Guide](/aws-setup). Instances are spawned and provisioned automatically. |
-| Any other machine (macOS, Linux, Windows, on-prem VM) | This guide. You start the runner yourself. |
+<EnterpriseCta feature="Running tests on your own machines" />
+
+<Note>
+  The runner only makes outbound connections, to the TestDriver API and to Ably for realtime messages. You don't need to open an inbound port.
+</Note>
 
-<Tip>
-  If you want unlimited execution, assisted setup, and custom VM images, see [Self-Hosted (Enterprise)](/self-hosted).
-</Tip>
+For Windows EC2 instances that start and stop automatically, use the [AWS setup](/aws-setup) instead.
 
-## Prerequisites
+## Before you begin
 
-Every machine that runs the runner needs:
+The machine needs:
 
-- **Node.js 18 or newer**
-- **Python 3** with `pyautogui` and `Pillow`
-- **A real, unlocked desktop session.** The runner drives the mouse and keyboard, so the screen must be awake and not locked. Disable screen savers, sleep, and lock timers.
-- **Google Chrome** on the `PATH`, if your tests launch a browser
-- Outbound HTTPS and WebSocket access to `api.testdriver.ai` and `*.ably.io`
+- **Node.js 18 or newer.**
+- **Python 3** with `pyautogui` and `Pillow`. The runner uses them for the mouse, keyboard, and screenshots.
+- **An unlocked desktop session.** The runner drives the real screen, so turn off sleep, screen savers, and lock timers.
+- **Outbound HTTPS and WebSocket access** to `api.testdriver.ai` and `*.ably.io`.
+- **`curl` and `jq`**, to register the machine in step 2.
 
-Install the Python dependencies:
+You also need your TestDriver API key in `TD_API_KEY`. Copy it from the [API keys page](https://console.testdriver.ai/team/api-keys).
 
 <Tabs>
   <Tab title="macOS">
+
     ```bash
-    brew install python
     pip3 install pyautogui Pillow
     ```
+
+    macOS blocks synthetic input and screen capture until you allow them. Open **System Settings → Privacy & Security** and add the terminal app that starts the runner to both lists:
+
+    - **Accessibility**, so the runner can move the mouse and type.
+    - **Screen Recording**, so the runner can take screenshots.
+
+    Quit and reopen the terminal after you change these settings.
+
   </Tab>
   <Tab title="Linux">
+
     ```bash
     sudo apt-get install -y python3-pip python3-xlib
     pip3 install pyautogui Pillow
     ```
-  </Tab>
-  <Tab title="Windows">
-    ```powershell
-    pip install pyautogui Pillow
-    ```
-  </Tab>
-</Tabs>
 
-### Platform notes
-
-<AccordionGroup>
-  <Accordion title="macOS: grant Accessibility and Screen Recording permissions">
-    macOS blocks synthetic input and screen capture until you allow it explicitly. Without this the runner connects but every click and screenshot silently fails.
-
-    Open **System Settings → Privacy & Security** and add your terminal application (Terminal, iTerm, or whichever app starts the runner) to **both**:
-
-    - **Accessibility** (lets the runner move the mouse and type)
-    - **Screen Recording** (lets the runner take screenshots)
-
-    Quit and reopen the terminal after granting permissions, otherwise the old process keeps the old denial.
-
-    On Retina displays, screenshots are captured at physical pixels and downscaled to logical points so that coordinates returned by the AI line up with where clicks actually land. No configuration is needed.
-  </Accordion>
-
-  <Accordion title="Linux: provide a display">
-    The runner needs an X11 display. On a desktop machine, set `DISPLAY` to your existing session. On a headless server, start a virtual framebuffer first:
+    The runner needs an X11 display. It uses `:0` unless `DISPLAY` is set. On a server without a desktop, start a virtual display first:
 
     ```bash
-    sudo apt-get install -y xvfb xfce4 xfce4-terminal dbus-x11 wmctrl
+    sudo apt-get install -y xvfb xfce4 dbus-x11
     Xvfb :0 -screen 0 1366x768x24 &
-    export DISPLAY=:0
+    DISPLAY=:0 startxfce4 &
     ```
 
-    To watch the session, add a VNC server and noVNC:
+    Turn off screen blanking so the desktop stays visible:
 
     ```bash
-    sudo apt-get install -y x11vnc novnc websockify
-    x11vnc -display :0 -forever -shared &
+    export DISPLAY=:0
+    xset s off && xset s noblank && xset -dpms
     ```
 
-    Disable screen blanking so the desktop stays visible:
+  </Tab>
+  <Tab title="Windows">
 
-    ```bash
-    xset s off && xset s noblank && xset -dpms
+    ```powershell
+    pip install pyautogui Pillow
     ```
-  </Accordion>
 
-  <Accordion title="Windows: keep the console session active">
-    Run the runner in a console or RDP session that stays signed in. If the session locks or disconnects, the desktop is torn down and automation stops. Configure the machine to auto-logon and disable the lock screen timeout.
-  </Accordion>
-</AccordionGroup>
+    Run the runner in a console or RDP session that stays signed in. If the session locks or disconnects, Windows tears down the desktop and automation stops. Set the machine to sign in automatically and turn off the lock screen.
+
+  </Tab>
+</Tabs>
 
 ## Step 1: Install the runner
 
@@ -114,208 +92,163 @@ Install the Python dependencies:
 npm install -g @testdriverai/runner
 ```
 
-This installs two commands. You use `testdriver-sandbox-agent`, which connects your machine to a TestDriver session.
-
-Verify the install:
-
-```bash
-testdriver-sandbox-agent --help || echo "installed"
-```
+This installs the `testdriver-sandbox-agent` command, which connects the machine to a TestDriver session.
 
 ## Step 2: Register the machine
 
-Ask the API for a session bound to your machine's IP address:
+Ask the API for a session on this machine. Replace `192.168.1.50` with the machine's IP address, and set `os` to `windows` on a Windows machine:
 
 ```bash
-curl -X POST https://api.testdriver.ai/api/v7/sandbox/authenticate \
+curl -sS -X POST https://api.testdriver.ai/api/v7/sandbox/authenticate \
   -H "Content-Type: application/json" \
-  -d '{
-    "apiKey": "your_api_key",
-    "ip": "192.168.1.50",
-    "os": "linux",
-    "keepAlive": 900000
-  }'
+  -d "{
+    \"apiKey\": \"$TD_API_KEY\",
+    \"apiRoot\": \"https://api.testdriver.ai\",
+    \"ip\": \"192.168.1.50\",
+    \"os\": \"linux\",
+    \"keepAlive\": 900000
+  }" > td-session.json
 ```
 
-The response contains the sandbox ID and the Ably credentials the runner needs:
-
-```json
-{
-  "success": true,
-  "sandboxId": "sb-69cce96e-1e0",
-  "agent": {
-    "token": {
-      "token": "aFC5YQ.Ki9G9...",
-      "keyName": "aFC5YQ.ZIdTww",
-      "issued": 1791908438832,
-      "expires": 1791930038832,
-      "capability": "{\"testdriver:...:sb-69cce96e-1e0\":[\"history\",\"presence\",\"publish\",\"subscribe\"]}",
-      "clientId": "agent-sb-69cce96e-1e0"
-    },
-    "channel": "testdriver:...:sb-69cce96e-1e0"
-  }
-}
-```
+The response includes a sandbox ID and an `agentConfig` object with everything the runner needs. Write `agentConfig` to the runner's config file, and print the sandbox ID:
 
-<Note>
-  Pass `os: "linux"` on macOS. The value only describes the session to the API; the runner detects the real platform itself.
-</Note>
-
-### Write the config file
-
-The runner reads its credentials from a JSON file on disk. Copy `sandboxId` and the whole `agent` block into it:
-
-| Platform | Config file path |
-|---|---|
-| macOS / Linux | `/tmp/testdriver-agent.json` |
-| Windows | `C:\Windows\Temp\testdriver-agent.json` |
-
-```json /tmp/testdriver-agent.json
-{
-  "sandboxId": "sb-69cce96e-1e0",
-  "apiRoot": "https://api.testdriver.ai",
-  "apiKey": "your_api_key",
-  "ably": {
-    "token": {
-      "token": "aFC5YQ.Ki9G9...",
-      "keyName": "aFC5YQ.ZIdTww",
-      "issued": 1791908438832,
-      "expires": 1791930038832,
-      "capability": "{\"testdriver:...:sb-69cce96e-1e0\":[\"history\",\"presence\",\"publish\",\"subscribe\"]}",
-      "clientId": "agent-sb-69cce96e-1e0"
-    },
-    "channel": "testdriver:...:sb-69cce96e-1e0"
-  }
-}
+```bash
+jq '.agentConfig' td-session.json > /tmp/testdriver-agent.json
+chmod 600 /tmp/testdriver-agent.json
+jq -r '.sandboxId' td-session.json
 ```
 
-| Field | Source | Purpose |
-|---|---|---|
-| `sandboxId` | `sandboxId` from the response | Identifies this session. Your test attaches to it. |
-| `apiRoot` | The API you called | Where the runner uploads screenshots |
-| `apiKey` | Your team API key | Authenticates those uploads |
-| `ably.token` | `agent.token` from the response, copied verbatim | Realtime credentials |
-| `ably.channel` | `agent.channel` from the response | Channel the runner listens on |
+On Windows, run these commands in Git Bash and write the file to `/c/Windows/Temp/testdriver-agent.json` instead.
 
-To put the file somewhere else, set `CONFIG_PATH` to its full path before starting the runner.
+Save the sandbox ID, such as `sb-69cce96e-1e0`, for step 4.
 
 <Warning>
-  This file holds a session token and your API key. Keep it readable only by the user running the runner, do not commit it, and delete it when the machine is no longer in use.
+  The config file contains your API key and a session token. Keep it readable only by the user who runs the runner, and never commit it.
 </Warning>
 
+To keep the config file somewhere else, set `CONFIG_PATH` to its full path before you start the runner.
+
+A registered machine uses one of your plan's concurrency slots while its session is open.
+
 ## Step 3: Start the runner
 
 ```bash
 testdriver-sandbox-agent
 ```
 
-You should see the runner connect and announce itself:
+The runner reads the config file, connects, and waits for commands:
 
+```text
+[2026-10-21T15:04:05.000Z] TestDriver Sandbox Agent starting...
+[2026-10-21T15:04:05.100Z] Sandbox ID: sb-69cce96e-1e0
+[2026-10-21T15:04:05.100Z] Transport: Ably
+[2026-10-21T15:04:06.200Z] Automation module initialized
+[2026-10-21T15:04:07.300Z] Agent ready — listening for commands via Ably
 ```
-[agent] TestDriver Sandbox Agent starting...
-[agent] Sandbox ID: sb-69cce96e-1e0
-[agent] Transport: Ably
-[agent] Automation module initialized
-[realtime] Publishing control: type=runner.ready
-[agent] Agent ready — listening for commands via Ably
-```
-
-Leave this process running. On Linux, set `DISPLAY` first:
 
-```bash
-DISPLAY=:0 testdriver-sandbox-agent
-```
+Leave it running. If the config file doesn't exist yet, the runner waits up to 5 minutes for it.
 
 ## Step 4: Point your test at the machine
 
-Pass the machine's `ip` and the sandbox ID from step 2:
+Pass the machine's `ip` and the `sandboxId` from step 2 to `TestDriver()`. Setting `sandboxId` stops TestDriver from creating a cloud sandbox.
 
 ```javascript tests/my-machine.test.mjs
-import { describe, expect, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+import { describe, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-describe("My machine", () => {
-  it("runs against my own hardware", async (context) => {
-    const testdriver = TestDriver(context, { newSandbox: false });
-
-    await testdriver.connect({
+describe('My machine', () => {
+  it('signs in to the desktop app', async (context) => {
+    const testdriver = TestDriver(context, {
       ip: process.env.TD_MACHINE_IP,
       sandboxId: process.env.TD_SANDBOX_ID,
     });
 
-    const button = await testdriver.find("Sign In button");
-    await button.click();
-
-    const result = await testdriver.assert("the dashboard is visible");
-    expect(result).toBeTruthy();
+    await testdriver.find('Sign in button').click();
+    await testdriver.assert('the dashboard is visible');
   });
 });
 ```
 
-Run it:
+On a Windows machine, also pass `os: 'windows'`.
+
+<Warning>
+  Run these tests with the `CI` environment variable unset. When `CI` is set, TestDriver always requests a new sandbox and ignores `sandboxId`, so the test waits for a runner that never connects.
+</Warning>
+
+Run the test from any computer:
 
 ```bash
-TD_MACHINE_IP=192.168.1.50 TD_SANDBOX_ID=sb-69cce96e-1e0 vitest run
+TD_MACHINE_IP=192.168.1.50 TD_SANDBOX_ID=sb-69cce96e-1e0 npx vitest run
 ```
 
-<Note>
-  `newSandbox: false` stops the SDK from provisioning a cloud sandbox. Without it, your test runs in the cloud and ignores your machine.
-</Note>
-
-<Note>
-  Each config file covers one session. The Ably token in it expires (see its `expires` field), so repeat steps 2 and 3 to get fresh credentials before the next run.
-</Note>
+Each registration covers one session. When the test disconnects, the session ends. Repeat steps 2 and 3 before the next run.
 
 ## Logs
 
 | Platform | Runner log |
-|---|---|
-| macOS / Linux | `/tmp/testdriver-agent.log` |
+| --- | --- |
+| macOS and Linux | `/tmp/testdriver-agent.log` |
 | Windows | `C:\Windows\Temp\testdriver-agent.log` |
 
-The runner also writes a status file next to the log (`testdriver-agent-status.json`) with the sandbox ID, process ID, detected IP, and start time.
+The runner also writes `testdriver-agent-status.json` in the same folder, with the sandbox ID, process ID, IP address, and start time.
 
 ## Security
 
-- **Use a dedicated machine or user account.** The runner can click anything on the desktop and run shell commands sent by your tests. Do not point it at a machine holding personal credentials or production access.
-- **Treat the config file as a secret.** It contains a session token and your API key.
-- **Do not expose VNC to the internet.** If you add VNC for debugging, bind it to localhost or your VPN and tunnel in over SSH.
-- **Rotate your API key** if a machine is decommissioned or shared.
+- **Use a dedicated machine or user account.** The runner can click anything on the desktop and run shell commands sent by your tests.
+- **Treat the config file as a secret.** It contains your API key and a session token.
+- **Keep VNC private.** If you add a VNC server for debugging, expose it only on localhost or your VPN.
+- **Rotate your API key** on the [API keys page](https://console.testdriver.ai/team/api-keys) when you retire or share a machine.
 
 ## Troubleshooting
 
 <AccordionGroup>
   <Accordion title="Sandbox has expired and is no longer available">
-    The session ended, which happens when the runner stops or your test disconnects. Repeat step 2 to get a fresh sandbox ID and token, update the config file, restart the runner, and use the new ID in your test.
-  </Accordion>
 
-  <Accordion title="Runner starts but clicks and screenshots do nothing (macOS)">
-    Accessibility or Screen Recording permission is missing. Add your terminal application to both lists under **System Settings → Privacy & Security**, then fully quit and reopen the terminal.
+    The session ended, which happens after a test disconnects or the session's `keepAlive` runs out. Repeat steps 2 and 3 for a fresh sandbox ID, and use the new ID in your test.
+
   </Accordion>
+  <Accordion title="The runner connects, but clicks and screenshots do nothing (macOS)">
+
+    Accessibility or Screen Recording permission is missing. Add your terminal app to both lists in **System Settings → Privacy & Security**, then quit and reopen it.
 
-  <Accordion title="Waiting for config file">
-    The runner cannot find `/tmp/testdriver-agent.json` (or `C:\Windows\Temp\testdriver-agent.json`). Write the config file on the same machine and readable by the same user that starts the runner. To use a different location, set `CONFIG_PATH`.
   </Accordion>
+  <Accordion title="Config file not found after 300s">
+
+    The runner couldn't find the config file. Write it on the same machine, readable by the user who starts the runner, or set `CONFIG_PATH` to where it is.
 
-  <Accordion title="Test provisions a cloud sandbox instead of using my machine">
-    Pass `newSandbox: false` to `TestDriver()` and make sure both `ip` and `sandboxId` reach `connect()`. If either is undefined, the SDK falls back to cloud provisioning.
   </Accordion>
+  <Accordion title="The test runs in a cloud sandbox instead">
+
+    Check that both `TD_MACHINE_IP` and `TD_SANDBOX_ID` are set when you run the test. If `sandboxId` is undefined, TestDriver creates a cloud sandbox.
 
-  <Accordion title="Invalid API key">
-    Confirm `TD_API_KEY` matches the environment in `TD_API_ROOT`. Keys are scoped per environment. Get your key at [console.testdriver.ai/team](https://console.testdriver.ai/team).
   </Accordion>
+  <Accordion title="Screenshots are blank or frozen (Linux)">
+
+    `DISPLAY` points at a display with no desktop, or the screen blanked. Start a desktop on that display and turn off blanking with `xset s off && xset s noblank && xset -dpms`.
 
-  <Accordion title="Screenshots are blank or show a frozen desktop (Linux)">
-    `DISPLAY` points at a display with no desktop running, or the screen blanked. Start a desktop on that display and disable blanking with `xset s off && xset s noblank && xset -dpms`.
   </Accordion>
 </AccordionGroup>
 
-## Environment variables
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `TD_API_KEY` | Required | Your team API key |
-| `TD_API_ROOT` | `https://api.testdriver.ai` | API server to register with |
-| `CONFIG_PATH` | `/tmp/testdriver-agent.json` | Override the runner config file location |
-| `DISPLAY` | `:0` | X11 display (Linux) |
-| `SENTRY_DSN` | Unset | Error reporting endpoint |
+## Runner environment variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CONFIG_PATH` | `/tmp/testdriver-agent.json`, or `C:\Windows\Temp\testdriver-agent.json` on Windows | Where the runner reads its config file |
+| `DISPLAY` | `:0` | The X11 display to drive (Linux) |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Self-host on AWS" icon="aws" href="/aws-setup">
+    Start a fresh Windows EC2 instance for each test.
+  </Card>
+  <Card title="Self-hosted" icon="server" href="/self-hosted">
+    What the Enterprise plan includes.
+  </Card>
+  <Card title="Locate elements" icon="crosshairs" href="/locating-elements">
+    Describe elements so TestDriver finds them on any screen.
+  </Card>
+  <Card title="Make assertions" icon="circle-check" href="/making-assertions">
+    Check that your app reached the right state.
+  </Card>
+</CardGroup>