| name | preview-deploy |
| description | Deploy a branch to a preview VM for zero-risk change review. Snapshot infra, clone it, deploy the branch on the clone, share the link. Production untouched. Use for ALL UI changes, feature demos, and PR reviews. |
Branch-to-Preview Deploy
Every change that has visible output should be demoed on a preview VM before merging. This is the standard review workflow.
When to use
- Any UI change (new tabs, widgets, visual fixes)
- New API endpoints that can be exercised via the dashboard
- Any change where "see it running" is more convincing than "read the diff"
- PR descriptions — include preview links where the change is visible
When NOT to use
- Pure backend refactors with no visible output
- Changes behind auth that can't be shared (note: magic links solve most of this)
- Trivial fixes (typos, comment changes)
The recipe
This is LT work. Delegate it — don't do it as the orchestrator.
1. Snapshot production infra
vers_vm_commit(infraVmId)
→ returns commitId
2. Clone from snapshot
vers_vm_restore(commitId)
→ returns preview VM ID
3. Deploy the branch on the clone
Task an LT with:
SSH to {previewVmId}.vm.vers.sh
cd /root/workspace/vers-agent-services
git fetch origin {branchName}
git checkout {branchName}
npm run build
systemctl restart agent-services
curl -s http://localhost:3000/health
4. Generate magic link
POST https://{previewVmId}.vm.vers.sh:3000/auth/magic-link
Authorization: Bearer {authToken}
5. Share with the human
Provide:
- Preview URL:
https://{previewVmId}.vm.vers.sh:3000
- for browser auth
