Preview Proxy#

AIO Sandbox includes built-in proxy endpoints that allow you to preview and test web applications and services directly from your development environment.

Proxy Types#

Frontend Application Proxy#

Access frontend applications using the absolute proxy:

Use cases:

• React, Vue, Angular applications
• Static site generators
• Development servers with asset bundling
• Any frontend framework with dev server

Example:

# Start a React app on port 3000
cd /workspace/my-react-app
npm start

# Access via proxy
# Browser: http://localhost:8080/absproxy/3000/

Backend Service Proxy#

Access backend services using the relative proxy:

Use cases:

• API servers
• Backend microservices
• Database admin interfaces
• Development tools and utilities

Example:

# Start an Express API on port 4000
cd /workspace/my-api
npm start

# Access via proxy
# API endpoint: http://localhost:8080/proxy/4000/api/users

Configuration Examples#

React Development Server#

# Start React app
npx create-react-app my-app
cd my-app
npm start  # Runs on port 3000

# Access at: http://localhost:8080/absproxy/3000/

Express API Server#

// server.js
const express = require('express');
const app = express();

app.get('/api/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date() });
});

app.listen(5000, () => {
  console.log('API server running on port 5000');
});

// Access at: http://localhost:8080/proxy/5000/api/health

Next.js Application#

# Start Next.js app
npx create-next-app@latest my-nextjs-app
cd my-nextjs-app
npm run dev  # Runs on port 3000

# Access at: http://localhost:8080/absproxy/3000/

Python Flask API#

# app.py
from flask import Flask, jsonify
app = Flask(__name__)

@app.route('/api/data')
def get_data():
    return jsonify({'message': 'Hello from Flask!', 'port': 5000})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

# Access at: http://localhost:8080/proxy/5000/api/data

Best Practices#

Frontend Applications#

1. Use absproxy for SPAs: Single Page Applications work best with absolute proxy
2. Configure base URL: Set your app's base URL to work with proxy
3. Handle routing: Ensure client-side routing works with proxy path

Backend Services#

1. Use proxy for APIs: Backend services should use the relative proxy
2. CORS configuration: Configure CORS to allow proxy domain
3. Health checks: Implement health check endpoints for monitoring

Development Workflow#

# Terminal 1: Start backend
cd /workspace/api
npm run dev  # Port 4000

# Terminal 2: Start frontend  
cd /workspace/frontend
npm start    # Port 3000

# Access:
# Frontend: http://localhost:8080/absproxy/3000/
# API: http://localhost:8080/proxy/4000/api/

Proxy Configuration#

Environment Variables#

Configure proxy behavior with environment variables:

# Maximum proxy connections
PROXY_MAX_CONNECTIONS=100

# Proxy timeout settings
PROXY_TIMEOUT=30

# Enable proxy logging
PROXY_DEBUG=true

Advanced Configuration#

For complex applications, you may need custom proxy settings:

// Custom proxy configuration example
const proxyConfig = {
  target: 'http://localhost:3000',
  changeOrigin: true,
  pathRewrite: {
    '^/absproxy/3000': ''
  },
  onProxyReq: (proxyReq, req, res) => {
    // Custom headers or modifications
    proxyReq.setHeader('X-Forwarded-Proto', 'http');
  }
};

Troubleshooting#

Common Issues#

Application not accessible via proxy:

• Check if application is running on specified port
• Verify application binds to 0.0.0.0 not just localhost
• Ensure no firewall blocking internal connections

CORS errors:

// Fix CORS for API servers
app.use(cors({
  origin: ['http://localhost:8080', 'http://localhost:3000'],
  credentials: true
}));

Asset loading issues:

// Configure React for proxy
// package.json
{
  "homepage": "/absproxy/3000/",
  "proxy": "http://localhost:4000"
}

Debug Commands#

# Check what's running on ports
netstat -tulpn | grep LISTEN

# Test direct connection
curl http://localhost:3000

# Test proxy connection
curl http://localhost:8080/absproxy/3000/

# Check proxy logs
docker logs aio-sandbox | grep proxy

Security Considerations#

Internal Access Only#

Proxy endpoints are designed for development use:

• Only accessible from within AIO Sandbox
• Not exposed to external networks by default
• Use reverse proxy for production deployments

Port Restrictions#

Some ports may be restricted:

• System ports (< 1024) require sudo
• Reserved ports for AIO Sandbox services
• Configure application to use available ports

Integration Examples#

With CI/CD Pipelines#

# GitHub Actions example
- name: Test in AIO Sandbox
  run: |
    # Start application
    npm start &
    
    # Wait for application to start
    sleep 10
    
    # Test via proxy
    curl -f http://localhost:8080/absproxy/3000/health

With Testing Frameworks#

// Cypress configuration
module.exports = {
  baseUrl: 'http://localhost:8080/absproxy/3000',
  video: false,
  screenshotOnRunFailure: false
};

Next Steps#

• Terminal Integration: Control services via shell → Shell API
• File Operations: Manage application files → File API
• Browser Automation: Test applications → Browser Guide