Testing Private Environments
Run Canary tests against staging apps behind a VPN or private network using our AWS integration.
By default, Canary runs browsers in the cloud that connect to your app over the public internet. For teams with staging environments behind a VPN or private network, you can deploy a Canary browser agent inside your AWS account so your staging environment never needs to be exposed.
How It Works
Canary places a small EC2 instance inside your AWS account that runs a real Chromium browser. The browser accesses your staging app over the local VPC network — no tunnel or public exposure required. Canary's AI test engine sends commands to the browser over a secure outbound WebSocket and receives results back through the same connection.
- You connect your AWS account to Canary using our AWS integration — this creates a cross-account IAM role with the minimum permissions needed to manage an EC2 instance in your VPC.
- Canary provisions and manages the EC2 instance in the VPC and subnet you specify. We handle the full lifecycle: launch, software installation, updates, and teardown.
- The instance runs a local Playwright (Chromium) browser and establishes an outbound-only WebSocket connection to Canary's cloud.
- When you trigger a test run, Canary's AI engine sends browser commands (navigate, click, type, screenshot, etc.) through the WebSocket to the local browser.
- The browser executes each command against your staging app over the VPC's internal network and returns results (page snapshots, screenshots, console logs) back to the cloud.
- The full test loop runs without any inbound traffic to your VPC.
Setup
- Connect your AWS account from the Canary dashboard's AWS integration page.
- This creates a cross-account IAM role with permissions scoped to EC2 instance management.
- Choose the VPC and subnet where the instance should run — this should be the same network as your staging app.
- Canary configures the security group to allow outbound HTTPS (443) only. No inbound rules are needed.
- Canary provisions the instance automatically.
- Instance type:
t3.medium(2 vCPU, 4 GB RAM), sized for running a real Chromium browser. - Canary installs the browser agent, authenticates it, and manages the full instance lifecycle (start, stop, updates, teardown).
- Instance type:
- Trigger test runs from the Canary dashboard or your CI/CD pipeline — the AI agent commands the local browser automatically.
Security Model
The in-VPC browser agent is designed for minimal attack surface:
- No inbound traffic — the EC2 instance only makes outbound connections on port 443 to Canary's cloud.
- No public exposure — your staging app remains fully private within the VPC.
- Scoped IAM role — the cross-account role only has the permissions needed to manage the browser instance.
- Encrypted transport — all communication between the instance and Canary's cloud uses WSS (WebSocket over TLS).
Comparing Your Options
Option A: Canary Browser Agent in Your VPC (Recommended for private environments)
| Pros | Cons |
|---|---|
| Staging environment stays fully private — no public exposure | Requires granting Canary a cross-account IAM role |
| Browsers run inside your VPC with local-network latency (fast) | EC2 instance cost (~$15–30/mo) |
| Only outbound traffic on port 443; simple security review | Initial setup requires choosing the correct VPC/subnet |
| Works with any internal service (localhost, private DNS, VPC endpoints) | |
| No DNS or firewall changes needed | |
| Fully managed by Canary — no maintenance on your side |
Option B: Expose Staging to the Internet
| Pros | Cons |
|---|---|
| Zero additional infrastructure — just add the URL | Staging environment is publicly accessible |
| Simplest setup; works in minutes | Expands your attack surface |
| No ongoing EC2 cost | May violate compliance requirements (SOC 2, HIPAA) |
| Requires DNS configuration and certificate management | |
| Risk of data exposure if staging contains production-like data |
Recommendation
For teams with publicly accessible staging environments, just add your staging URL as a property — you can be running tests in minutes with no extra infrastructure.
For teams with private staging environments or compliance requirements, the AWS integration keeps your security posture intact. You connect your AWS account once, and Canary handles the rest. The browser runs locally in your VPC so page interactions are fast, and the only external communication is the outbound WebSocket to Canary's cloud.