VPC Environments

01Overview

VPC environments let you test internal applications that are not publicly accessible, such as services behind a private ALB or in a private subnet. Canary provisions a temporary EC2 instance inside your VPC, runs a headless browser on it, and streams browser commands to and from the Canary cloud over WebSocket.

In your property's Environments table, VPC-backed environments now appear alongside your other environment types, including permanent environments, local environments, and sandbox-backed ephemeral environments. Use the environment type and expiry details in that table to quickly distinguish long-lived VPC environments from temporary sandbox environments.

02Architecture

1. You configure an environment with your AWS VPC details (IAM role, subnet, security group).
2. When a test suite runs, Canary assumes the IAM role and launches an EC2 instance in your subnet.
3. The instance runs a lightweight CLI that connects back to Canary's API via WebSocket (outbound HTTPS through your NAT gateway).
4. Canary controls the browser remotely, executing your test workflows against internal URLs.
5. After the suite completes, the EC2 instance is terminated automatically.

Connection pooling

When a test suite contains multiple workflows targeting the same VPC environment, Canary provisions one EC2 instance per environment (not one per workflow). The browser process is shared, and credential isolation is handled at the browser context level — each workflow gets a fresh context loaded with its own credential's storage state.

03Prerequisites

Before configuring a VPC environment, ensure:

• NAT gateway: The subnet must have a route to the internet (via NAT gateway) so the EC2 instance can connect back to Canary's API.
• IAM role: Create a role that Canary can assume (cross-account STS) with permissions to launch and terminate EC2 instances in your VPC.
• Subnet: A private subnet in the VPC where the browser instance will run.
• Security group: Must allow outbound HTTPS (port 443) to Canary's API, and any ports needed to reach your internal application.

04Setup

1. Navigate to your property's Environments tab.
2. Click Add Environment and fill in the name and internal URL.
3. Enable Run tests in customer AWS VPC.
4. Provide the required fields:
   • IAM Role ARN: The cross-account role Canary will assume (for example, arn:aws:iam::123456789012:role/CanaryVpcBrowser).
   • Subnet ID: The private subnet for the browser instance.
   • Security Group ID: Controls network access for the browser instance.
   • AWS Region: The region where your VPC resides.
5. Click Create.

After you create the environment, return to the shared Environments table to confirm it appears as a VPC-backed environment. That same table may also show temporary sandbox-backed ephemeral environments and other environment types for the property, so use the environment type and expiry information to identify the entry you want before you run tests or open environment actions.

05Managing environments

Use the Environments table to review and manage all environments for the property in one place. The refreshed list makes it easier to scan each row before you edit settings or choose a default environment.

Each environment row can show the following details:

Use the row actions to open the environment, edit its settings, or manage the default environment selection. If your property contains both long-lived and temporary environments, check the type and expiration columns before making changes.

06Editing environment settings

Edit a VPC environment directly from the Environments table.

1. Open your property's Environments tab.
2. Find the VPC environment you want to update.
3. Review the row details, including Environment type, VPC status, and Updated.
4. Open the row actions and click Edit.
5. Update the fields you need, then click Save.

When you edit the environment URL, Canary now handles common formatting issues more gracefully. If you enter a host name without http:// or https://, Canary adds the protocol automatically.

07Default environment selection

Choose the default environment from the refreshed actions in the Environments table.

1. Open your property's Environments tab.
2. Find the environment you want to use by default.
3. Open the row actions.
4. Click the action to set the environment as the default.

Use the environment details in the table to confirm you are selecting the correct environment, especially if your property includes temporary environments that may expire.

IAM trust policy

Your IAM role needs a trust policy allowing Canary to assume it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<canary-account-id>:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your-org-id>"
        }
      }
    }
  ]
}

IAM permissions

The role needs these EC2 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:DescribeInstances",
        "ec2:CreateTags"
      ],
      "Resource": "*"
    }
  ]
}

08URL requirements and validation

Enter the application URL in a standard web format that points to the internal app you want Canary to test.

• Use a valid host name or full URL.
• If you omit the protocol, Canary adds https:// automatically when possible.
• If the URL is invalid or unsafe, Canary shows a clearer validation message so you can correct it before saving.
• Use the final saved URL to confirm Canary will target the right internal application.

If Canary rejects the URL, check for common issues such as unsupported schemes, malformed host names, or accidental spaces.

09Related

• Use Sandboxes when you need a dedicated environment management surface for GitHub-connected repositories, template creation, or sandbox instance management. See /docs/reference/sandboxes.
• Use VPC environments when you need Canary to run tests against private applications inside your AWS network without managing sandbox templates or instances.

10Troubleshooting

Browser doesn't connect (timeout after 120s)

• Verify the subnet has a NAT gateway with a route to the internet.
• Check that the security group allows outbound HTTPS on port 443.
• Ensure the IAM role has ec2:RunInstances permission in the specified region.

Tests fail with "No browser available"

• The EC2 instance may have been terminated before the test completed. Check if your security group or VPC flow logs show connection drops.

IAM assume role errors

• Verify the trust policy includes Canary's AWS account ID and your organization ID as the external ID.
• Ensure the role ARN is correct and the role exists in the specified region.

Subnet or security group not found

• Confirm the subnet ID and security group ID are in the same region as configured.
• The security group must belong to the same VPC as the subnet.

URL validation errors

• Re-enter the URL without extra spaces or unsupported characters.
• If you entered only a host name, save again and let Canary add the protocol automatically.
• If Canary shows an unsafe or invalid URL message, verify that the host and scheme point to the internal application you expect to test.