@requestma/local-agent

Local agent for forwarding webhooks from Request.ma to your localhost development environment.

Quick Start

# Install and run in one command
npx @requestma/local-agent --endpoint YOUR_ENDPOINT_ID --token YOUR_TOKEN --port 3000

# With auto-discovery
npx @requestma/local-agent --endpoint YOUR_ENDPOINT_ID --token YOUR_TOKEN --discover

Installation

The agent can be run directly with npx (recommended) or installed globally:

# Direct execution (recommended)
npx @requestma/local-agent

# Global installation
npm install -g @requestma/local-agent
requestma-agent --help

Usage

Basic Usage

Forward webhooks to a specific port:

npx @requestma/local-agent \
  --endpoint q5jh94a321a6uw40tb153gdz \
  --token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --port 3000

Auto-Discovery

Automatically discover running services:

npx @requestma/local-agent \
  --endpoint q5jh94a321a6uw40tb153gdz \
  --token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --discover

Advanced Options

npx @requestma/local-agent \
  --endpoint q5jh94a321a6uw40tb153gdz \
  --token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... \
  --port 8000 \
  --host localhost \
  --server wss://api.request.ma \
  --verbose

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --endpoint <id> | -e | Request.ma endpoint ID | Required | | --token <token> | -t | Authentication token | Required | | --port <port> | -p | Target localhost port | Auto-detect | | --host <host> | -h | Target localhost host | localhost | | --server <url> | -s | Request.ma server URL | wss://api.request.ma | | --discover | -d | Auto-discover local services | false | | --verbose | -v | Verbose logging | false |

How It Works

1. Authentication: Agent connects to Request.ma using your endpoint token
2. Service Discovery: Optionally scans common ports for running services
3. WebSocket Connection: Maintains persistent connection for real-time forwarding
4. Request Forwarding: Receives webhooks and forwards them to your local server
5. Response Handling: Captures local server responses and sends them back

Supported Frameworks

The agent automatically detects common development frameworks:

• React (ports 3000, 3001, 5173, 5174)
• Next.js (ports 3000, 3001)
• Express.js (ports 3000, 8000)
• FastAPI (ports 8000, 8080)
• Flask (ports 5000, 8000)
• Django (ports 8000, 8080)
• Rails (ports 3000, 4000)
• Vite (ports 5173, 5174)

Security

• JWT Authentication: Secure token-based authentication
• Local Only: Agent only connects to localhost services
• No Elevated Permissions: Runs with normal user permissions
• Open Source: Full source code available for security auditing

Troubleshooting

Connection Issues

# Check if your local service is running
curl http://localhost:3000

# Test with verbose logging
npx @requestma/local-agent -e YOUR_ENDPOINT -t YOUR_TOKEN -p 3000 --verbose

Service Discovery Issues

# Force discovery with verbose output
npx @requestma/local-agent -e YOUR_ENDPOINT -t YOUR_TOKEN --discover --verbose

Token Issues

• Tokens are endpoint-specific and expire after 24 hours
• Get a new token from the Request.ma Actions panel
• Ensure the endpoint ID matches your webhook endpoint

Examples

React Development Server

# Start your React app
npm start  # Usually runs on port 3000

# In another terminal, start the agent
npx @requestma/local-agent -e abc123 -t xyz789 -p 3000

FastAPI Development

# Start your FastAPI app
uvicorn main:app --reload --port 8000

# Start the agent
npx @requestma/local-agent -e abc123 -t xyz789 -p 8000

Multiple Services with Discovery

# Start multiple services on different ports
npm start &          # React on 3000
uvicorn main:app &    # FastAPI on 8000

# Discover and select service
npx @requestma/local-agent -e abc123 -t xyz789 --discover

License

MIT

Support

• Documentation: https://request.ma/docs/local-agent
• Issues: https://github.com/requestma/webhooks/issues
• Discord: https://discord.gg/requestma