Skip to main content

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:
  1. Go to Actions tab in GitHub
  2. Select “Deploy to Vast.ai” workflow
  3. Click “Run workflow”
  4. Select branch (usually main)
  5. 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:
Response:

2. SSH Deploy

Connects to Vast.ai instance and runs scripts/deploy-vast.sh: Key Steps:
  1. Install bun if not present
  2. Clone repository (first-time setup)
  3. Pull latest code from main
  4. Restore environment variables from /tmp (survives git reset)
  5. Install system dependencies (FFmpeg, Vulkan, Chrome Dev, PulseAudio)
  6. Setup PulseAudio virtual sink for audio capture
  7. Install Playwright and dependencies
  8. Build core packages
  9. Setup Solana keypair from SOLANA_DEPLOYER_PRIVATE_KEY
  10. Push database schema with drizzle-kit
  11. Warmup database connection (3 retry attempts)
  12. Kill PM2 daemon (ensures fresh environment)
  13. Start port proxies (socat)
  14. Explicitly unset and re-export stream keys
  15. Start duel stack via PM2
  16. Wait for health check to pass (120s timeout)
  17. 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
Recommended:
  • 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 modules
  • python3 - Required for some build tools
  • git-lfs - Git Large File Storage
  • ffmpeg - Video encoding and streaming
  • socat - Port proxying
  • xvfb - Virtual framebuffer for headful GPU rendering
  • pulseaudio + pulseaudio-utils - Audio capture
  • mesa-vulkan-drivers - Vulkan drivers
  • vulkan-tools - Vulkan utilities
  • libvulkan1 - Vulkan library
  • wget, gnupg, curl, jq - Utilities
Chrome Dev Channel:
Playwright:

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:
Deploy Script:
Without this persistence mechanism, the server would fail to start due to missing DATABASE_URL.

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 because pm2 delete only removes processes, not the daemon’s cached environment.

Solution

Use pm2 kill instead of pm2 delete:
Impact: Environment variables (stream keys, DATABASE_URL) are properly loaded on every deployment.

Database Warmup

Problem

Cold starts caused database connection failures, leading to server crash-loops.

Solution

Add warmup step after schema push with retry logic:
Benefits:
  • 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:
2. Configure User Mode:
3. Start PulseAudio:
4. Export Environment Variables:

FFmpeg Audio Configuration

Audio Input:
Audio Encoding:

Graceful Fallback

If PulseAudio is not available, FFmpeg falls back to silent audio:

Troubleshooting Audio

Check PulseAudio status:
Verify chrome_audio sink:
Test audio capture:
Restart PulseAudio:

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
YouTube streaming is explicitly disabled. Set YOUTUBE_STREAM_KEY="" to prevent stale keys from being used.

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
Low Latency Mode:
  • Uses ‘zerolatency’ tune
  • 2x buffer size (9000k)
  • No B-frames
  • Recommended for interactive streams

Canonical Platform

Platform Defaults:
  • youtube → 15000ms delay
  • twitch → 12000ms delay
  • hls → 4000ms delay

Port Mappings

Vast.ai uses socat for port proxying: Setup:

Solana Keypair Setup

The deployment automatically configures Solana keypairs from SOLANA_DEPLOYER_PRIVATE_KEY:
Environment Variable Fallbacks:
All three roles default to the same deployer keypair for simplified configuration.

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:
Install Drivers:

Chrome Dev Channel

For latest WebGPU features:

Xvfb for Headful Rendering

Streaming Settings

PM2 Configuration

Troubleshooting

Stream Not Appearing

1. Check stream keys:
2. Check FFmpeg processes:
3. Check RTMP status:
4. Check PM2 logs:

Database Connection Issues

Check DATABASE_URL:
Test connection:

GPU Rendering Issues

Check Vulkan:
Check Chrome:
Check Xvfb:

Audio Issues

Check PulseAudio:
Restart PulseAudio:

PM2 Commands

Maintenance Mode API

Enter Maintenance Mode

Response:

Exit Maintenance Mode

Check Status

Response:

First-Time Setup

The deployment automatically handles first-time setup:
Bun Installation:

DNS Configuration

Some Vast containers use internal-only DNS. The deploy script configures Google DNS:

Deployment Summary

After successful deployment, the script outputs:

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