kakuremichi E2E test environment (Vagrant + Hyper-V)

Two test modes are provided.

Mode	VMs	Speed	Use case
Single-VM (default)	1	fast	quick smoke test, local iteration
Multi-VM (control / gateway / agent)	3	slower	realistic deployment, cross-host WireGuard, failover experiments

Prerequisites

• Windows 11 + Hyper-V enabled
• Vagrant (winget install Hashicorp.Vagrant)
• For multi-VM: bash, curl, jq, openssl on the host (Git Bash or WSL works)

---

Mode 1 — Single VM

One Ubuntu 24.04 VM runs Control + Gateway + Agent + origin all together.

cd C:\Users\neo\GitHub\kakuremichi-org\test
vagrant up --provider=hyperv default
vagrant ssh default

Then inside the VM:

cd /kakuremichi/test && sudo bash run-full-test.sh

12 Phase:

#	What
1	Go build + -race unit tests (gateway & agent)
2	Control server (dev:custom, Next.js + WS on :3000)
3	Admin bootstrap via env or /setup → login → mint admin PAT → register Gateway / Agent / Tunnel with Bearer auth
4	Create wg0 kernel interface + self-signed TLS cert
5	Start Agent
6	Start Gateway (with TLS enabled from the start)
7	WireGuard tunnel verification (peer listing, IP, ping)
8	Inbound HTTP proxy (Host: test.local → origin)
9	Exit Node HTTP + SOCKS5 proxy
10	Inbound HTTPS via the same cert
11	Auth/authz (401/403/409 matrix, logout)
12	DB integrity (FK cascade, concurrent tunnel creation, subnet UNIQUE)

---

Mode 2 — Multi-VM

Three separate VMs, host-side orchestration. Gateway and Agent genuinely cross the network boundary over WireGuard.

Quick path (Windows-native, PowerShell)

One command from an elevated (Administrator) PowerShell:

cd C:\Users\neo\GitHub\kakuremichi-org\test
.\Run-MultiVmTest.ps1 -Up

-Up does vagrant up first (skip it on subsequent runs). Per-VM logs (control / gateway / agent / origin) are dumped into test\logs\ at the end so you can inspect without another vagrant ssh.

Other flags:

• -SkipBuild — skip Go build + unit tests (for fast iteration)

Underneath, the script drives the exact same flow as the bash orchestrator (multi-vm/run-multi-vm-test.sh) but via PowerShell + curl.exe only — no WSL / Git Bash needed.

Topology

host ──HTTP/HTTPS──┐
                   ▼
       ┌──────────────────────┐       ┌──────────────────────┐
       │ gateway VM           │──WG──▶│ agent VM             │
       │  wg0 kernel          │       │  netstack WG         │
       │  HTTP :8880/:8443    │       │  origin :9000        │
       │  ExitNode :8080/:1080│       │  exit proxy 127.0.0.1│
       └──────────┬───────────┘       └──────────┬───────────┘
                  │ WebSocket                    │ WebSocket
                  └──────────────┬───────────────┘
                                 ▼
                   ┌──────────────────────┐
                   │ control VM           │
                   │  Next.js + WS :3000  │
                   └──────────────────────┘

1. Bring up the VMs (once, from admin PowerShell)

cd C:\Users\neo\GitHub\kakuremichi-org\test
vagrant up --provider=hyperv control gateway agent

This boots three Ubuntu 24.04 VMs. Each takes ~2 minutes. When prompted, use the same Windows credentials for the SMB share on every VM.

2. Run the multi-VM test suite (from host bash)

bash multi-vm/run-multi-vm-test.sh

Orchestration steps, executed by the host against each VM via vagrant ssh:

1. Detect hostname -I for each VM (CONTROL_IP / GATEWAY_IP / AGENT_IP)
2. build-unit-test.sh on gateway + agent in parallel (-race)
3. control-start.sh boots Control with ADMIN_EMAIL env bootstrap
4. Host-side curl: login → mint admin PAT → register Gateway (with the detected public IP) / Agent / Tunnel
5. Ship a fresh self-signed TLS cert to the gateway VM via vagrant upload
6. agent-start.sh, then gateway-start.sh
7. wg show wg0 + cross-VM ping on gateway
8. Host-side HTTP + HTTPS through http://${GATEWAY_IP}:8880/ (and :8443)
9. curl --proxy from the agent VM → Exit Node HTTP + SOCKS5
10. Auth/authz matrix + FK cascade test (API only)

3. Inspecting logs

Per-VM logs stay on each VM:

vagrant ssh control -c 'tail -50 /tmp/control.log'
vagrant ssh gateway -c 'tail -50 /tmp/gateway.log'
vagrant ssh agent   -c 'tail -50 /tmp/agent.log'

4. Re-running

control-start.sh / gateway-start.sh / agent-start.sh kill leftover processes up front, so just re-run bash multi-vm/run-multi-vm-test.sh.

5. Tear-down

vagrant destroy -f

---

Layout

test/
├── Vagrantfile                # single + multi-VM definitions
├── run-full-test.sh           # single-VM 12-Phase test
├── README.md
└── multi-vm/
    ├── run-multi-vm-test.sh   # HOST-side orchestrator
    ├── control-start.sh       # runs on control VM
    ├── gateway-start.sh       # runs on gateway VM
    ├── agent-start.sh         # runs on agent VM
    └── build-unit-test.sh     # runs on gateway/agent VM (Go build + -race tests)

Notes & known limitations

• Hyper-V Default Switch is used for all VMs. VM-to-VM traffic goes over the same switch; IPs are assigned via DHCP and detected at test time.
• Only one gateway VM is provisioned today. To test multi-gateway failover you can add a gateway2 block in Vagrantfile mirroring gateway, wire it up in the orchestrator, and the agent will already fail over between gateway addresses (see agent/internal/exitnode/* + the change in agent/cmd/agent/main.go).
• The SMB mount is read/write. Binaries are built inside each VM under /tmp so SMB latency does not affect the actual run paths.