RunPod Proxy Server

A smart proxy server that automatically manages RunPod instance lifecycle, starting pods when needed and stopping them after periods of inactivity to save costs.

Note

The code and this readme have been created with Claude code.

How It Works

The proxy server acts as an intelligent middleware between your local applications and your RunPod instances:

1. Automatic Pod Management: Starts your RunPod instance when the first request arrives
2. Request Proxying: Forwards all HTTP requests to your running pod
3. Idle Detection: Monitors request activity and stops the pod after a configurable timeout
4. Cost Optimization: Minimizes compute costs by only running pods when actively used

Features

• ✅ Automatic pod start/stop lifecycle management
• ✅ Configurable idle timeout (default: 5 minutes)
• ✅ Random port selection when no port specified
• ✅ Health check endpoint
• ✅ Graceful shutdown with pod cleanup
• ✅ Comprehensive logging and error handling
• ✅ ESM module support

Setup

1. Install Dependencies

npm install

2. Configure Environment

Copy the example environment file and fill in your RunPod details:

cp .env.dist .env

Edit .env with your configuration:

# Your RunPod API key (found in your RunPod account settings)
RUNPOD_API_KEY=your_runpod_api_key_here

# The URL of your RunPod instance (e.g., https://your-pod-id-8080.proxy.runpod.net)
PROXIED_URL=https://your-pod-endpoint.proxy.runpod.net

# Your RunPod instance/pod ID
RUNPOD_INSTANCE_ID=your_pod_id

# Local server port (optional - random port used if not specified)
PORT=3000

# Timeout in milliseconds (optional - defaults to 5 minutes)
TIMEOUT=300000

3. Run the Server

npm start

The server will start and display:

• Local proxy URL
• Target RunPod URL
• Pod ID being managed
• Configured timeout
• Health check endpoint

Usage

Making Requests

Once running, send requests to your local proxy server instead of directly to RunPod:

# Instead of: curl https://your-pod.proxy.runpod.net/api/endpoint
curl http://localhost:3000/api/endpoint

The proxy will:

1. Check if the pod is running
2. Start the pod if it's stopped (waits for startup)
3. Forward your request to the pod
4. Return the pod's response
5. Start the idle timeout counter

Health Check

Check proxy status:

curl http://localhost:3000/health

Response includes:

• Proxy server status
• Pod running state
• Last request timestamp
• Configured timeout

Stopping

The server handles graceful shutdown:

# Ctrl+C or:
kill -SIGINT <process_id>

This will automatically stop the RunPod instance before exiting.

Configuration

Environment Variables

Variable	Required	Default	Description
RUNPOD_API_KEY	✅	-	Your RunPod API key
PROXIED_URL	✅	-	RunPod instance endpoint URL
RUNPOD_INSTANCE_ID	✅	-	RunPod pod/instance ID
PORT	❌	Random	Local server port
TIMEOUT	❌	300000	Idle timeout in milliseconds

Finding Your Configuration

RunPod API Key:

• Go to RunPod → Settings → API Keys
• Create a new API key if needed

Pod ID:

• In your RunPod dashboard, click on your pod
• The ID is shown in the pod details

Pod URL:

• In your pod details, look for the "Connect" section
• Use the HTTP service URL (usually ends with .proxy.runpod.net)

Lifecycle Management

Pod States

• Stopped: Pod is not running (saving money)
• Starting: Pod is booting up (may take 30-60 seconds)
• Running: Pod is active and receiving requests
• Stopping: Pod is shutting down after idle timeout

Cost Optimization

The proxy helps minimize RunPod costs by:

1. On-Demand Starting: Only starts pods when requests arrive
2. Automatic Stopping: Stops pods after the configured idle period
3. Smart Monitoring: Tracks request activity to determine when it's safe to stop

Troubleshooting

Common Issues

"Missing required environment variables"

• Ensure .env file exists and contains all required variables
• Double-check variable names match exactly

"Pod failed to start within timeout period"

• Your pod may take longer to start than expected
• Check your pod's Docker image and startup time
• Verify the pod isn't stuck or has configuration issues

"Proxy error" responses

• Verify your PROXIED_URL is correct and accessible
• Check that your pod is properly configured to accept HTTP requests
• Ensure any required authentication is handled by your pod

Port already in use

• The proxy will automatically try a different random port
• Or specify a different PORT in your .env file

Debugging

Enable detailed logging by checking the console output. The proxy logs:

• Pod status checks
• Start/stop operations
• Request proxying
• Timeout events
• Errors and warnings

Development

Running in Development

npm run dev

License

ISC - See package.json for details.

---

Caution

This proxy is designed for development and testing purposes. For production use, consider additional features like authentication, rate limiting, and monitoring.