npm package: @requestma/local-agent
Description: Local agent for forwarding webhooks from Request.ma to localhost
Author: Request.ma Team
Latest version: 1.0.2

# @requestma/local-agent

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

## Quick Start

```bash
# 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:

```bash
# 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:

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

### Auto-Discovery

Automatically discover running services:

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

### Advanced Options

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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