Local Sandbox Setup

This guide covers setting up Windows VMs on your own machine using Hyper-V. Great for development and testing.

Overview

For local testing, you can run multiple Windows 11 VMs using Hyper-V. This gives you full control over your automation environment.

Windows Sandbox only allows one instance at a time. For parallel testing, use Hyper-V VMs instead.

Prerequisites

OS: Windows 11 Pro/Enterprise/Education (Hyper-V not available on Home)
RAM: 16GB+ recommended (4GB per VM + host overhead)
CPU: SLAT support (most modern CPUs)

Step 1: Enable Hyper-V

Run in elevated PowerShell:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Reboot when prompted. Verify by opening “Hyper-V Manager” from Start menu.

Step 2: Download Windows 11 ISO

Get the ISO

Go to: Microsoft Evaluation Center

Download

Download the 64-bit ISO (90-day evaluation, free)

Save

Save to C:\ISOs\Win11Enterprise.iso

Step 3: Create Virtual Switch

In Hyper-V Manager → Virtual Switch Manager → New virtual network switch:

Setting	Value
Type	External
Name	`External-Internet`
External network	Select your physical NIC

This gives VMs internet access and makes them reachable from host.

Step 4: Create Base VM

In Hyper-V Manager → Action → New → Virtual Machine:

Setting	Value
Name	`cua-base-template`
Generation	2 (required for TPM/Windows 11)
Memory	4096 MB (uncheck dynamic memory)
Network	`External-Internet`
Virtual Hard Disk	60 GB, dynamically expanding
Installation	Mount the Windows 11 ISO

After creation, configure security:

Right-click VM → Settings → Security
Enable “Enable Trusted Platform Module”
Secure Boot: Microsoft UEFI Certificate Authority

Start VM and install Windows 11.

Step 5: Configure Base VM

After Windows installation, configure the VM.

Create Local Account

Create a local admin account (e.g., cua-agent with your password). Avoid Microsoft account for simpler automation.

Enable Remote Desktop

Settings → System → Remote Desktop → Enable

Allow connections from any version of Remote Desktop.

Set Static IP (Recommended)

Settings → Network & Internet → Ethernet → Edit IP settings

Example IPs for your VMs:

VM1: 192.168.1.101
VM2: 192.168.1.102
VM3: 192.168.1.103

Disable Windows Update (Optional)

Prevents surprise reboots during testing:

# Run as admin
Stop-Service wuauserv
Set-Service wuauserv -StartupType Disabled

Install Python 3.12

Use Python 3.12, NOT 3.13+ (pywin32 compatibility issues)

Download from python.org and install with “Add to PATH” checked.

Install Driver Dependencies

pip install pyautogui mss pillow rpaframework websockets

Clone and Setup Driver

cd C:\
git clone <your-repo-url> granite
cd granite\driver
pip install -r requirements.txt

Create Checkpoint

In Hyper-V Manager:

Right-click VM → Checkpoint
Name it clean-base-with-driver

This allows quick revert to clean state.

Step 6: Clone VMs

Export Base VM

Shut down the base VM
Right-click → Export
Save to C:\Hyper-V\Exports\

Import as Copies

GUI
PowerShell

Action → Import Virtual Machine
Select the exported folder
Choose “Copy the virtual machine (create a new unique ID)”
Select new storage location

Import-VM -Path "C:\Hyper-V\Exports\cua-base-template\Virtual Machines\*.vmcx" -Copy -GenerateNewId

Configure Each Clone

For each cloned VM:

Rename in Hyper-V Manager: cua-local-01, cua-local-02, etc.
Start VM and change computer name
Assign unique static IP
Update client_machine_id in driver config (must be unique)

Step 7: Start VMs and Register Drivers

Start all VMs in Hyper-V Manager
In each VM, run the driver application
Driver will auto-register with backend via WebSocket
Verify machines appear in Driver Management

Step 8: Add RDP Credentials

For each registered VM, update RDP credentials so the agent can connect:

from backend.utils.mongo.vm_keys_mongodb import update_rdp_credentials

update_rdp_credentials(
    driver_machine_id="<id-from-mongodb>",
    rdp_username="cua-agent",
    rdp_password="your-password",
    rdp_external_ip="192.168.1.101",
    rdp_port=3389
)

Or update directly in MongoDB:

{
  "rdp_username": "cua-agent",
  "rdp_password": "your-password",
  "rdp_external_ip": "192.168.1.101",
  "rdp_port": 3389
}

Quick Reference Commands

# Start all CUA VMs
Get-VM -Name "cua-local-*" | Start-VM

# Stop all CUA VMs
Get-VM -Name "cua-local-*" | Stop-VM

# Check VM status
Get-VM -Name "cua-local-*" | Select Name, State, CPUUsage, MemoryAssigned

# Revert to clean checkpoint
Restore-VMCheckpoint -Name "clean-base-with-driver" -VMName "cua-local-01" -Confirm:$false

# Revert all VMs to checkpoint
Get-VM -Name "cua-local-*" | Restore-VMCheckpoint -Name "clean-base-with-driver" -Confirm:$false

Resource Planning

Configuration	RAM per VM	Total VMs	VM RAM Usage	Host Available
16GB system	4GB	2	8GB	~8GB
32GB system	4GB	3	12GB	~20GB
32GB system	4GB	5	20GB	~12GB

Troubleshooting

Issue	Solution
Can’t RDP to VM	Check Windows Firewall allows RDP (port 3389)
VM not appearing in MongoDB	Verify driver is running and WebSocket URL is correct
RDP connection fails from backend	Verify `rdp_external_ip` matches VM’s actual IP
VM runs slow	Disable dynamic memory, ensure host has RAM headroom
TPM error during Windows install	Enable TPM in VM Settings → Security
90-day eval expires	Create fresh VM from ISO, re-run setup steps
Network conflicts	Ensure each VM has unique computer name and IP

Architecture Notes

The local Hyper-V setup integrates with the existing backend architecture:

Driver Registration: Driver connects via WebSocket and calls register_or_update_driver_machine() automatically
RDP Credentials: Stored in MongoDB, retrieved by agent via get_rdp_credentials()
Job Execution: Backend dispatches jobs to VMs via the same job queue system
No Backend Changes Required: The architecture is VM-agnostic; local Hyper-V VMs work identically to cloud VMs

Get Started

Getting Started

Dashboard

Agent Execution

RPA Automation

Public API

VM Management

Driver

Troubleshooting

Local Sandbox Setup

Overview

Prerequisites

Step 1: Enable Hyper-V

Step 2: Download Windows 11 ISO

Step 3: Create Virtual Switch

Step 4: Create Base VM

Step 5: Configure Base VM

Create Local Account

Enable Remote Desktop

Set Static IP (Recommended)

Disable Windows Update (Optional)

Install Python 3.12

Install Driver Dependencies

Clone and Setup Driver

Create Checkpoint

Step 6: Clone VMs

Export Base VM

Import as Copies

Configure Each Clone

Step 7: Start VMs and Register Drivers

Step 8: Add RDP Credentials

Quick Reference Commands

Resource Planning

Troubleshooting

Architecture Notes

​Overview

​Prerequisites

​Step 1: Enable Hyper-V

​Step 2: Download Windows 11 ISO

​Step 3: Create Virtual Switch

​Step 4: Create Base VM

​Step 5: Configure Base VM

​Create Local Account

​Enable Remote Desktop

​Set Static IP (Recommended)

​Disable Windows Update (Optional)

​Install Python 3.12

​Install Driver Dependencies

​Clone and Setup Driver

​Create Checkpoint

​Step 6: Clone VMs

​Export Base VM

​Import as Copies

​Configure Each Clone

​Step 7: Start VMs and Register Drivers

​Step 8: Add RDP Credentials

​Quick Reference Commands

​Resource Planning

​Troubleshooting

​Architecture Notes

Overview

Prerequisites

Step 1: Enable Hyper-V

Step 2: Download Windows 11 ISO

Step 3: Create Virtual Switch

Step 4: Create Base VM

Step 5: Configure Base VM

Create Local Account

Enable Remote Desktop

Set Static IP (Recommended)

Disable Windows Update (Optional)

Install Python 3.12

Install Driver Dependencies

Clone and Setup Driver

Create Checkpoint

Step 6: Clone VMs

Export Base VM

Import as Copies

Configure Each Clone

Step 7: Start VMs and Register Drivers

Step 8: Add RDP Credentials

Quick Reference Commands

Resource Planning

Troubleshooting

Architecture Notes