@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/aws-setup.mdx

@@ -1,238 +1,180 @@
 ---
-title: "AWS Setup Guide"
-sidebarTitle: "AWS Setup Guide"
-description: "Deploy TestDriver on your AWS infrastructure using CloudFormation"
+title: "Self-host on AWS"
+sidebarTitle: "AWS setup guide"
+description: "Run each test on a fresh Windows EC2 instance in your AWS account, set up with CloudFormation."
 icon: "aws"
 ---
 
-This guide helps you to set up self-hosted TestDriver instances on AWS. At the end, you have automated test infrastructure. It starts and stops instances when you need them.
+import { EnterpriseBadge, EnterpriseCta } from '/snippets/enterprise.mdx';
 
-```mermaid
-graph LR
-    A[Vitest Test] --> B[setup-aws hook]
-    B --> C[Spawns EC2]
-    C --> D[Runs Test]
-    D --> E[Terminates EC2]
-```
-
-## How It Works
-
-TestDriver manages the AWS EC2 instances for your tests automatically:
-
-1. **Deploy CloudFormation**. Set up the infrastructure one time.
-2. **Configure Vitest**. Add one line to your config.
-3. **Run Tests**. The instances start automatically, run the tests, and stop.
-
-That is all. You do not need to manage the instances by hand.
-
-# Quickstart
-
-<Steps>
-  <Step title="Deploy Infrastructure">
-    <Card 
-      title="Launch CloudFormation Stack" 
-      icon="aws" 
-      href="https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://v7-cloudformation-template.s3.us-east-2.amazonaws.com/cloudformation.yaml" 
-      horizontal 
-      arrow
-    >
-      One-click AWS setup
-    </Card>
-  </Step>
-  
-  <Step title="Add to Vitest Config">
-    ```javascript vitest.config.mjs
-    setupFiles: ['testdriverai/vitest/setup', 'testdriverai/vitest/setup-aws']
-    ```
-  </Step>
-  
-  <Step title="Run Tests">
-    ```bash
-    TD_OS=windows AWS_REGION=us-east-2 \
-      AWS_LAUNCH_TEMPLATE_ID=lt-xxx AMI_ID=ami-xxx \
-      vitest run
-    ```
-  </Step>
-</Steps>
+Run your Windows tests on EC2 instances in your own AWS account. For each test, TestDriver:
 
-## Overview
+1. Launches a fresh instance from the TestDriver AMI.
+2. Installs and starts the runner on it over AWS Systems Manager (SSM).
+3. Runs the test, then terminates the instance.
 
-The setup process is simple:
+A CloudFormation stack creates the network, security group, IAM role, and launch template the instances need. You deploy it once.
 
-1. **Deploy CloudFormation** — Creates VPC, security groups, IAM roles, and launch templates
-2. **Configure Vitest** — Add `setup-aws` to automatically manage instance lifecycle
-3. **Run Tests** — Set `TD_OS=windows` with AWS credentials and instances spawn/terminate automatically
+<EnterpriseCta feature="Self-hosting on AWS" />
 
+<Note>
+  Self-hosting is part of the Enterprise plan. See [Self-hosted](/self-hosted).
+</Note>
 
-## Prerequisites
+## Before you begin
 
-Before you begin, ensure you have:
+- **Access to the TestDriver AMI.** TestDriver shares it with your AWS account. [Contact TestDriver](https://testdriver.ai/enterprise) with your account ID and region to get the AMI ID.
+- **The AWS CLI**, [installed](https://aws.amazon.com/cli/) and signed in, on every machine that runs tests (your laptop and your CI runners).
+- **`jq`**, which the instance launch script uses to read AWS responses.
+- **A TestDriver project** with your API key in `TD_API_KEY`. See [Set up a project](/quickstart-manual).
 
-- AWS account with CloudFormation permissions
-- [AWS CLI](https://aws.amazon.com/cli/) installed and configured (`aws configure`)
-- Access to the TestDriver AMI — [Contact us](https://testdriver.ai/enterprise) with your AWS region
-- A GitHub repository for your tests
+## Step 1: Deploy the CloudFormation stack
 
-<Tip>
-  The TestDriver Golden Image AMI ID is `ami-0504bf50fad62f312`. Contact us to get access in your preferred AWS region.
-</Tip>
+The template creates:
 
-## Step 1: Deploy CloudFormation Stack
-
-Our CloudFormation template creates all the AWS infrastructure you need:
-
-- Dedicated VPC with public subnet
-- Security group with required port access
-- IAM roles and instance profiles
-- EC2 launch template for instance creation
+- A VPC with a public subnet and internet gateway.
+- A security group that allows RDP, VNC, and web traffic from the IP range you choose.
+- An IAM role and instance profile with SSM access.
+- An EC2 launch template, and optionally a key pair.
 
 <Tabs>
-  <Tab title="GUI">
-    Click the button below to launch the CloudFormation stack in your AWS Console:
-
-    <Card 
-      title="Launch Stack" 
-      icon="aws" 
-      href="https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://v7-cloudformation-template.s3.us-east-2.amazonaws.com/cloudformation.yaml" 
-      horizontal 
-      arrow
-    >
-      Deploy TestDriver infrastructure with one click
-    </Card>
+  <Tab title="AWS console">
 
-    Configure the stack parameters:
-    - **Stack name**: `testdriver-infrastructure` (or your preferred name)
-    - **ProjectTag**: `testdriver`
-    - **AllowedIngressCidr**: Your IP range (e.g., `203.0.113.0/24`)
-    - **InstanceType**: `c5.xlarge` (recommended)
-    - **CreateKeyPair**: `true`
-
-    <Warning>
-      **Security**: Replace `AllowedIngressCidr` with your specific IP ranges to restrict VPC access. Avoid using `0.0.0.0/0` in production.
-    </Warning>
-
-    ### Get Your Launch Template ID
+    <Card title="Launch the stack" icon="aws" href="https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https://v7-cloudformation-template.s3.us-east-2.amazonaws.com/cloudformation.yaml" horizontal arrow>
+      Open the template in the CloudFormation console.
+    </Card>
 
-    After the stack creation completes, navigate to the **Outputs** tab to find your `LaunchTemplateId`:
+    Switch the console to the region you'll run tests in, fill in the parameters below, and create the stack.
 
-    ![Launch Template ID](/images/content/self-hosted/launchtemplateid.png)
+    When the stack finishes, open its **Outputs** tab and copy `LaunchTemplateId`.
 
-    <Tip>
-      **Save this ID** — you'll need it for spawning instances and CI configuration.
-    </Tip>
   </Tab>
-  <Tab title="CLI">
-    Download the template from the [TestDriver CLI repository](https://github.com/testdriverai/testdriverai/blob/main/setup/aws/cloudformation.yaml), then deploy:
+  <Tab title="AWS CLI">
+
+    The template ships with the SDK. From your project, deploy it with:
 
     ```bash
     aws cloudformation deploy \
-      --template-file setup/aws/cloudformation.yaml \
+      --region us-east-2 \
+      --template-file node_modules/testdriverai/setup/aws/cloudformation.yaml \
       --stack-name testdriver-infrastructure \
       --parameter-overrides \
-        ProjectTag=testdriver \
-        AllowedIngressCidr=0.0.0.0/0 \
+        AllowedIngressCidr=203.0.113.0/24 \
         InstanceType=c5.xlarge \
-        CreateKeyPair=true \
+        CreateKeyPair=yes \
       --capabilities CAPABILITY_IAM
     ```
 
-    <Warning>
-      **Security**: Replace `AllowedIngressCidr=0.0.0.0/0` with your specific IP ranges to restrict VPC access.
-    </Warning>
-
-    ### Get Your Launch Template ID
-
-    After deployment completes, retrieve the launch template ID:
+    Then get the launch template ID:
 
     ```bash
     aws cloudformation describe-stacks \
+      --region us-east-2 \
       --stack-name testdriver-infrastructure \
       --query 'Stacks[0].Outputs[?OutputKey==`LaunchTemplateId`].OutputValue' \
       --output text
     ```
 
-    <Tip>
-      **Save this ID** — you'll need it for spawning instances and CI configuration.
-    </Tip>
   </Tab>
 </Tabs>
 
-## Step 2: Configure Vitest
+### Stack parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `AllowedIngressCidr` | `0.0.0.0/0` | The IP range allowed to reach the instances over RDP and VNC. Set it to your office or VPN range. |
+| `InstanceType` | `c5.xlarge` | The EC2 instance type. Allowed: `c5.xlarge` to `c5.24xlarge`, `c5.metal`, or `i3.metal`. |
+| `CreateKeyPair` | `yes` | `yes` creates a new key pair. `no` uses the key named in `ExistingKeyName`. |
+| `ExistingKeyName` | | An existing EC2 key pair. Required when `CreateKeyPair` is `no`. |
+| `ProjectTag` | `testdriver` | The `Project` tag added to every resource. |
+| `NotificationEmail` | | An email address to notify when the stack finishes. Optional. |
+
+<Warning>
+  The default `AllowedIngressCidr` of `0.0.0.0/0` opens RDP and VNC to the whole internet. Set it to your own IP range.
+</Warning>
 
-Add the AWS setup hook to your `vitest.config.mjs`:
+## Step 2: Add the AWS setup file to Vitest
+
+Add `testdriverai/vitest/setup-aws` to `setupFiles`. It launches an instance before each test that runs on Windows.
 
 ```javascript vitest.config.mjs
 import { defineConfig } from 'vitest/config';
-import { config } from 'dotenv';
 import TestDriver from 'testdriverai/vitest';
 
-config(); // Load .env file
-
 export default defineConfig({
   test: {
     testTimeout: 900000,
     hookTimeout: 900000,
-    maxConcurrency: 3,
-    reporters: [
-      'default',
-      TestDriver(),
-      ['junit', { outputFile: 'test-report.junit.xml' }]
-    ],
+    reporters: ['default', TestDriver()],
     setupFiles: ['testdriverai/vitest/setup', 'testdriverai/vitest/setup-aws'],
   },
 });
 ```
 
-<Note>
-  **That's it!** The `setup-aws` hook automatically spawns and terminates instances when `TD_OS=windows` is set. No manual instance management needed.
-</Note>
+The 15-minute `hookTimeout` gives a new instance time to boot, pass its status checks, and register with SSM.
 
-## Step 3: Write Your Tests
+## Step 3: Write your test
 
-Tests should use `context.ip || process.env.TD_IP` for the IP configuration:
+Your tests don't change. The setup file passes the instance's IP address and ID to `TestDriver()` for you:
 
-```javascript
-import { describe, it } from "vitest";
-import { TestDriver } from "testdriverai/vitest/hooks";
+```javascript tests/login.test.mjs
+import { describe, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-describe("My Test", () => {
-  it("should run on self-hosted instance", async (context) => {
-    const testdriver = TestDriver(context, {
-      ip: context.ip || process.env.TD_IP,
-    });
+describe('Login', () => {
+  it('shows the login page', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-    await testdriver.provision.chrome({ url: "https://example.com" });
-    // ... your test steps
+    await testdriver.assert('the login form is visible');
   });
 });
 ```
 
-<Note>
-  **How it works**: When `TD_OS=windows` with AWS credentials, `context.ip` is automatically set by the setup hook. When running without AWS setup (cloud-hosted), both are undefined and TestDriver uses the cloud. When `TD_IP` is provided manually, it takes precedence.
-</Note>
-
-## Step 4: Run Tests
+## Step 4: Run the tests
 
-### Locally
+Set `TD_OS=windows` to turn on the setup file, along with your launch template and AMI:
 
 ```bash
 TD_OS=windows \
 AWS_REGION=us-east-2 \
-AWS_LAUNCH_TEMPLATE_ID=lt-xxx \
-AMI_ID=ami-0504bf50fad62f312 \
-vitest run
+AWS_LAUNCH_TEMPLATE_ID=lt-0123456789abcdef0 \
+AMI_ID=ami-0123456789abcdef0 \
+npx vitest run
 ```
 
-<Note>
-  Each test gets its own fresh EC2 instance that's automatically terminated after completion.
-</Note>
+Each test gets its own instance. The instance is terminated after the test ends, once its recording has stopped. If the test process exits early, TestDriver terminates any instances still running.
+
+When `TD_OS` isn't `windows`, the setup file does nothing and tests run on TestDriver's cloud.
+
+### Environment variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `TD_OS` | | Set to `windows` to launch instances. Required. |
+| `AWS_LAUNCH_TEMPLATE_ID` | | `LaunchTemplateId` from the stack outputs. Required. |
+| `AMI_ID` | | The TestDriver AMI, or your own AMI built from it. Required. |
+| `AWS_REGION` | `us-east-2` | The region of your stack and AMI. |
+| `AWS_LAUNCH_TEMPLATE_VERSION` | `$Latest` | The launch template version to use. |
+| `RESOLUTION` | `1920x1080` | The instance's screen resolution. |
+| `AWS_TAG_PREFIX` | `td` | Prefix for each instance's `Name` tag, followed by a timestamp. |
+
+The AWS CLI reads your credentials from its usual sources, such as `aws configure`, `AWS_PROFILE`, or `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
 
-### In GitHub Actions
+### AWS permissions
 
-Automate testing with self-hosted instances in your CI/CD pipeline. TestDriver automatically spawns a fresh instance for each test, runs the test, and terminates the instance.
+The credentials that run your tests need these actions:
 
-```yaml .github/workflows/test.yml
-name: TestDriver Self-Hosted Windows Tests
+- `ec2:RunInstances`, `ec2:CreateTags`, `ec2:DescribeInstances`, `ec2:DescribeInstanceStatus`, and `ec2:TerminateInstances`
+- `iam:PassRole` for the stack's instance role
+- `ssm:DescribeInstanceInformation`, `ssm:SendCommand`, and `ssm:GetCommandInvocation`
+
+## Run in GitHub Actions
+
+This workflow authenticates to TestDriver with the [TestDriver action](/ci-cd#github-actions) and to AWS with stored access keys:
+
+```yaml .github/workflows/testdriver-windows.yml
+name: Windows tests
 
 on:
   push:
@@ -242,208 +184,148 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    
+    permissions:
+      id-token: write
+      contents: read
+
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: 'npm'
 
-      - name: Install dependencies
-        run: npm ci
+      - run: npm ci
+
+      - uses: testdriverai/action@stable
 
-      - name: Run Windows tests with self-hosted instances
-        run: vitest run examples/*.test.mjs
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-2
+
+      - name: Run tests on Windows instances
+        run: npx vitest run
         env:
-          TD_API_KEY: ${{ secrets.TD_API_KEY }}
           TD_OS: windows
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          AWS_REGION: us-east-2
           AWS_LAUNCH_TEMPLATE_ID: ${{ secrets.AWS_LAUNCH_TEMPLATE_ID }}
           AMI_ID: ${{ secrets.AMI_ID }}
-
-      - name: Upload test results
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: test-results
-          path: test-report.junit.xml
 ```
 
-<Note>
-  **Automatic Instance Management**: Setting `TD_OS=windows` with AWS credentials enables automatic instance spawning. Each test gets its own fresh instance that's terminated after the test completes.
-</Note>
-
-### Required GitHub Secrets
-
-| Secret | Description | Example |
-|--------|-------------|---------|
-| `AWS_ACCESS_KEY_ID` | AWS access key | `AKIAIOSFODNN7EXAMPLE` |
-| `AWS_SECRET_ACCESS_KEY` | AWS secret key | `wJalrXUtnFEMI/K7MDENG...` |
-| `AWS_REGION` | AWS region | `us-east-2` |
-| `AWS_LAUNCH_TEMPLATE_ID` | From CloudFormation output | `lt-07c53ce8349b958d1` |
-| `AMI_ID` | TestDriver AMI ID | `ami-0504bf50fad62f312` |
-| `TD_API_KEY` | Your TestDriver API key | From [console.testdriver.ai](https://console.testdriver.ai) |
+GitHub's `ubuntu-latest` runners already include the AWS CLI and `jq`.
 
 <Tip>
-  Add these as **GitHub Repository Secrets** under Settings → Secrets and variables → Actions
+  To avoid storing AWS keys, give `configure-aws-credentials` a `role-to-assume` instead. The job's `id-token: write` permission covers both TestDriver and AWS. See [GitHub's OIDC guide](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
 </Tip>
 
-### Example Workflows
-
-For complete production examples, see:
-- **[Scheduled Tests](https://github.com/testdriverai/testdriverai/blob/main/.github/workflows/acceptance-windows-scheduled.yaml)** — Daily automated test runs
-- **[Reusable Workflow](https://github.com/testdriverai/testdriverai/blob/main/.github/workflows/windows-self-hosted.yaml)** — Shared configuration for PR and scheduled tests
-
-## Advanced Usage
-
-### Using an Existing Instance
-
-If you already have a running instance, you can skip automatic spawning by providing `TD_IP`:
-
-```bash
-TD_OS=windows TD_IP=1.2.3.4 vitest run
-```
-
-The `setup-aws` hook will detect `TD_IP` is already set and skip spawning a new instance.
-
-### Manual Instance Management
-
-For advanced use cases, you can manually spawn instances using the [`spawn-runner.sh`](https://github.com/testdriverai/testdriverai/blob/main/setup/aws/spawn-runner.sh) script:
+## Connect to an instance
 
-```bash
-AWS_REGION=us-east-2 \
-AMI_ID=ami-0504bf50fad62f312 \
-AWS_LAUNCH_TEMPLATE_ID=lt-xxx \
-bash setup/aws/spawn-runner.sh
-```
+To watch or debug a test, connect to its instance over RDP on port 3389 while it runs. The setup file prints the instance's IP address when it launches it.
 
-Output:
-```
-PUBLIC_IP=1.2.3.4
-INSTANCE_ID=i-1234567890abcdef0
-AWS_REGION=us-east-2
-```
-
-Then manually terminate when done:
-
-```bash
-aws ec2 terminate-instances \
-  --instance-ids i-1234567890abcdef0 \
-  --region us-east-2
-```
+The TestDriver AMI signs in as the user `testdriver`. Ask TestDriver for the default password, and change it before you build your own image.
 
-For complete production examples, see:
-- **[Scheduled Tests](https://github.com/testdriverai/testdriverai/blob/main/.github/workflows/acceptance-windows-scheduled.yaml)** — Daily automated test runs
-- **[Reusable Workflow](https://github.com/testdriverai/testdriverai/blob/main/.github/workflows/windows-self-hosted.yaml)** — Shared configuration for PR and scheduled tests
+## Create a custom AMI
 
-### Connecting to an Instance
+Preinstall your apps and test data so tests don't spend time on setup.
 
-You can connect to running instances via:
-- **RDP** — Use the public IP on port 3389
-- **VNC** — Access via web browser at `http://<public-ip>:5900`
-- **AWS Console** — Use EC2 Instance Connect or Session Manager
-
-<Note>
-  Stopped instances retain their EBS volumes and can be restarted later. Terminated instances are permanently deleted. Always terminate instances when done to avoid storage costs.
-</Note>
+<Steps>
+  <Step title="Launch an instance and connect">
 
-## AMI Customization
+    Launch an instance from the TestDriver AMI with the stack's launch template:
 
-The TestDriver Golden Image comes pre-configured with:
+    ```bash
+    aws ec2 run-instances \
+      --region us-east-2 \
+      --image-id ami-0123456789abcdef0 \
+      --launch-template 'LaunchTemplateId=lt-0123456789abcdef0,Version=$Latest'
+    ```
 
-- Windows Server with desktop environment
-- VNC + web server for remote access
-- Python, Node.js, Git
-- TestDriver agent and dependencies
+    When it's running, connect to its public IP address over RDP.
 
-### Creating a Custom AMI
+  </Step>
+  <Step title="Rotate the default password">
 
-You can customize the AMI to include additional software or configurations:
+    Run the password rotation script and save the new password:
 
-<Steps>
-  <Step title="Connect via RDP">
-    Use the default credentials:
-    - **Username**: `testdriver`
-    - **Password**: `wwv9uJ0sqlulbN3`
-  </Step>
-  
-  <Step title="Change the Password">
-    **Critical**: Run the password rotation script immediately:
     ```powershell
     C:\testdriver\RotateLocalPasswords.ps1
     ```
-    Save the new password securely.
-  </Step>
-  
-  <Step title="Install Your Software">
-    Install any additional dependencies, configure settings, or modify the environment as needed.
+
   </Step>
-  
-  <Step title="Create New AMI">
-    Use the AWS console or CLI to create an AMI from your modified instance. Update your workflow to use the new AMI ID.
+  <Step title="Install your software">
+
+    Install your apps, dependencies, certificates, and data.
+
   </Step>
-</Steps>
+  <Step title="Create the AMI">
 
-<Warning>
-  **Security**: Never use the default password in production. Always rotate passwords before creating custom AMIs.
-</Warning>
+    Create an image from the instance:
 
-## Security Best Practices
+    ```bash
+    aws ec2 create-image \
+      --region us-east-2 \
+      --instance-id i-0123456789abcdef0 \
+      --name my-testdriver-image
+    ```
 
-### Network Security
+    Set `AMI_ID` to the new image's ID when you run tests.
 
-- **Restrict CIDR blocks** — Only allow access from known IP ranges
-- **Use VPC endpoints** — For private AWS service communication
-- **Enable VPC Flow Logs** — For network monitoring
+  </Step>
+</Steps>
 
-### AWS Authentication
+## Troubleshooting
 
-Use OIDC instead of long-term credentials for GitHub Actions:
+<AccordionGroup>
+  <Accordion title="TD_OS=windows requires AWS_LAUNCH_TEMPLATE_ID and AMI_ID">
 
-```yaml
-permissions:
-  id-token: write
-  contents: read
+    Set both variables in the environment that runs `npx vitest run`. In CI, check that the secrets are passed to the test step.
 
-steps:
-  - name: Configure AWS credentials
-    uses: aws-actions/configure-aws-credentials@v4
-    with:
-      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
-      aws-region: us-east-2
-```
+  </Accordion>
+  <Accordion title="AWS CLI is not installed">
 
-See [GitHub's OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for setup instructions.
+    Install the [AWS CLI](https://aws.amazon.com/cli/) on the machine that runs the tests, and check that `aws` is on the `PATH`.
 
-### Instance Security
+  </Accordion>
+  <Accordion title="SSM registration timeout">
 
-- **Terminate immediately** after tests complete
-- **Monitor costs** with AWS billing alerts
-- **Use least-privilege IAM roles**
-- **Enable CloudTrail** for audit logging
+    The instance didn't register with Systems Manager. Check that:
 
-## Troubleshooting
+    - The launch template from the stack is used, so the instance gets the stack's IAM role.
+    - The instance is in the stack's public subnet, so it can reach SSM.
+    - The AMI is the TestDriver AMI, or an image built from it.
 
-### Instance Not Responding
+  </Accordion>
+  <Accordion title="A test fails before it starts with a hook timeout">
 
-- **Check security groups** — Verify required ports are open (RDP 3389, VNC 5900, TestDriver ports)
-- **Verify status checks** — Ensure instance has passed AWS status checks
-- **Check AMI compatibility** — Some instance types don't support certain AMIs
+    Launching and preparing an instance takes several minutes. Raise `hookTimeout` in `vitest.config.mjs`.
 
-### Connection Timeouts
+  </Accordion>
+  <Accordion title="Instances are left running">
 
-- Verify network connectivity from CI runner to instance
-- Check VPC routing and internet gateway configuration
-- Confirm instance is in the correct subnet
+    TestDriver terminates instances after each test and when the process exits. A killed CI job can still leave one behind. Find instances by their `Name` tag, which starts with `td-`, and terminate them:
 
-### AWS CLI Errors
+    ```bash
+    aws ec2 terminate-instances --region us-east-2 --instance-ids i-0123456789abcdef0
+    ```
 
-- Validate credentials and permissions
-- Check service quotas and limits
-- Verify region consistency across all resources
+  </Accordion>
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Run on your own machine" icon="display" href="/bring-your-own-machine">
+    Run the runner on a laptop, lab machine, or on-prem VM.
+  </Card>
+  <Card title="Run tests in CI/CD" icon="code-branch" href="/ci-cd">
+    Authenticate and run tests in any CI provider.
+  </Card>
+  <Card title="Self-hosted" icon="server" href="/self-hosted">
+    What the Enterprise plan includes.
+  </Card>
+  <Card title="Launch apps" icon="rocket" href="/provision">
+    Start Chrome, desktop apps, and installers in the sandbox.
+  </Card>
+</CardGroup>