Overview
Hyperscape deploys to Vast.ai for GPU-accelerated game streaming with automated CI/CD. This deployment enables:- GPU-accelerated rendering with WebGPU + Vulkan
- Multi-platform RTMP streaming (Twitch, Kick, X/Twitter)
- PulseAudio audio capture for game music and sound effects
- Automated maintenance mode for graceful deployments
- Health monitoring and diagnostics
Automated Deployment
The.github/workflows/deploy-vast.yml workflow automatically deploys on push to main:
Manual Deployment
Trigger deployments manually from GitHub Actions UI:- Go to Actions tab in GitHub
- Select “Deploy to Vast.ai” workflow
- Click “Run workflow”
- Select branch (usually
main) - Click “Run workflow”
Manual deployment is useful for hotfixes, instance restarts, or testing the deployment process.
Deployment Process
The deployment follows these steps:1. Enter Maintenance Mode
Pauses new duel cycles and waits for active markets to resolve:2. SSH Deploy
Connects to Vast.ai instance and runsscripts/deploy-vast.sh:
Key Steps:
- Install bun if not present
- Clone repository (first-time setup)
- Pull latest code from main
- Restore environment variables from
/tmp(survives git reset) - Install system dependencies (FFmpeg, Vulkan, Chrome Dev, PulseAudio)
- Setup PulseAudio virtual sink for audio capture
- Install Playwright and dependencies
- Build core packages
- Setup Solana keypair from
SOLANA_DEPLOYER_PRIVATE_KEY - Push database schema with drizzle-kit
- Warmup database connection (3 retry attempts)
- Kill PM2 daemon (ensures fresh environment)
- Start port proxies (socat)
- Explicitly unset and re-export stream keys
- Start duel stack via PM2
- Wait for health check to pass (120s timeout)
- Run streaming diagnostics
3. Exit Maintenance Mode
Resumes duel cycles after health check passes:Required GitHub Secrets
Configure these in Settings → Secrets → Actions:System Requirements
Vast.ai Instance Specs
Minimum Requirements:- GPU: NVIDIA with Vulkan support (RTX 3060 Ti or better)
- RAM: 16GB minimum
- Storage: 50GB minimum
- OS: Ubuntu 22.04 or Debian 12
- GPU: RTX 4090 or RTX 3090
- RAM: 32GB
- Storage: 100GB SSD
Installed Dependencies
The deployment script automatically installs: System Packages:build-essential- C/C++ compiler for native modulespython3- Required for some build toolsgit-lfs- Git Large File Storageffmpeg- Video encoding and streamingsocat- Port proxyingxvfb- Virtual framebuffer for headful GPU renderingpulseaudio+pulseaudio-utils- Audio capturemesa-vulkan-drivers- Vulkan driversvulkan-tools- Vulkan utilitieslibvulkan1- Vulkan librarywget,gnupg,curl,jq- Utilities
Environment Variable Persistence
Problem
git reset --hard operations in the deploy script would overwrite the .env file, losing critical configuration like DATABASE_URL and stream keys.
Solution
Write secrets to/tmp before git reset, then restore after:
GitHub Workflow:
Stream Key Management
Problem
Vast.ai servers can have stale stream keys in their shell environment from previous deployments. These stale values override the.env file values, causing streams to go to wrong channels.
Solution
Explicitly unset and re-export stream keys before PM2 start:This ensures PM2 picks up the correct stream keys from the
.env file, not stale values from the shell environment.PM2 Environment Variable Handling
Problem
PM2 wasn’t picking up new environment variables on restart becausepm2 delete only removes processes, not the daemon’s cached environment.
Solution
Usepm2 kill instead of pm2 delete:
Database Warmup
Problem
Cold starts caused database connection failures, leading to server crash-loops.Solution
Add warmup step after schema push with retry logic:- Verifies database connection before starting server
- Retries up to 3 times to handle cold starts
- Prevents server crash-loops from database connection failures
PulseAudio Audio Capture
Overview
The deployment configures PulseAudio to capture game audio (music and sound effects) for RTMP streams.Setup Process
1. Install PulseAudio:FFmpeg Audio Configuration
Audio Input:Graceful Fallback
If PulseAudio is not available, FFmpeg falls back to silent audio:Troubleshooting Audio
Check PulseAudio status:Streaming Configuration
Multi-Platform RTMP
Streams simultaneously to:- Twitch:
rtmp://live.twitch.tv/app - Kick:
rtmps://fa723fc1b171.global-contribute.live-video.net/app - X/Twitter:
rtmp://sg.pscp.tv:80/x
Streaming Quality Settings
Balanced Mode (Default):- Uses ‘film’ tune with B-frames
- 4x buffer size (18000k)
- Better compression and smoother playback
- Recommended for passive viewing
- Uses ‘zerolatency’ tune
- 2x buffer size (9000k)
- No B-frames
- Recommended for interactive streams
Canonical Platform
youtube→ 15000ms delaytwitch→ 12000ms delayhls→ 4000ms delay
Port Mappings
Vast.ai uses socat for port proxying:
Setup:
Solana Keypair Setup
The deployment automatically configures Solana keypairs fromSOLANA_DEPLOYER_PRIVATE_KEY:
Health Monitoring
Health Check Endpoint
Post-Deploy Diagnostics
The deploy script automatically runs comprehensive diagnostics:Health Check Wait
The deployment waits up to 120 seconds for the server to become healthy:GPU Configuration
Vulkan Support
Check Vulkan:Chrome Dev Channel
For latest WebGPU features:Xvfb for Headful Rendering
Streaming Settings
PM2 Configuration
Troubleshooting
Stream Not Appearing
1. Check stream keys:Database Connection Issues
Check DATABASE_URL:GPU Rendering Issues
Check Vulkan:Audio Issues
Check PulseAudio:PM2 Commands
Maintenance Mode API
Enter Maintenance Mode
Exit Maintenance Mode
Check Status
First-Time Setup
The deployment automatically handles first-time setup:DNS Configuration
Some Vast containers use internal-only DNS. The deploy script configures Google DNS:Deployment Summary
After successful deployment, the script outputs:Related Documentation
Maintenance Mode API
Graceful deployment system for production
Audio Streaming
PulseAudio audio capture setup
RTMP Streaming
Multi-platform streaming configuration
Configuration
Environment variables and settings