Pixcap VPN Connector

Capture screenshots of internal websites through the Pixcap API. Deploy this connector inside your network to screenshot private dashboards, staging environments, and internal applications.

Quick Start

Docker (Recommended)

docker run -d \
  -e PIXCAP_CONNECTOR_TOKEN=pxc_your_token \
  --restart unless-stopped \
  --name pixcap-connector \
  dashah2/pixcap-connector

npm

npm install -g pixcap-connector
PIXCAP_CONNECTOR_TOKEN=pxc_your_token pixcap-connector

From Source

git clone https://github.com/dan-shah/pixcap.git
cd dashah2/pixcap-connector
npm install
PIXCAP_CONNECTOR_TOKEN=pxc_your_token npm start

Get Your Token

1. Log in to pixcap.dev/dashboard
2. Scroll to VPN Connectors section
3. Click Create New Connector
4. Copy the token (shown only once!)
5. Note your Connector ID for API requests

Take a Screenshot

Once your connector is running and shows "Online" in the dashboard:

curl "https://pixcap.dev/api/v1/screenshot?url=http://internal.example.com&connector_id=conn_YOUR_ID" \
  -H "X-API-Key: pix_YOUR_API_KEY" \
  -o screenshot.png

POST Request (JSON)

curl -X POST "https://pixcap.dev/api/v1/screenshot" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pix_YOUR_API_KEY" \
  -d '{
    "url": "http://internal.example.com",
    "connectorId": "conn_YOUR_ID",
    "width": 1920,
    "height": 1080
  }' \
  -o screenshot.png

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | PIXCAP_CONNECTOR_TOKEN | (required) | Your connector token from the dashboard | | PIXCAP_API_URL | wss://pixcap.dev/ws/connector | WebSocket endpoint URL | | SCREENSHOT_TIMEOUT | 30000 | Screenshot timeout in milliseconds | | PUPPETEER_EXECUTABLE_PATH | (auto-detect) | Path to Chrome/Chromium executable | | DEFAULT_VIEWPORT_WIDTH | 1280 | Default viewport width | | DEFAULT_VIEWPORT_HEIGHT | 800 | Default viewport height |

How It Works

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Your App       │      │  Pixcap Cloud    │      │  Connector      │
│                 │      │                  │      │  (Your Network) │
└────────┬────────┘      └────────┬─────────┘      └────────┬────────┘
         │                        │                         │
         │ 1. API Request         │                         │
         │ with connector_id      │                         │
         │───────────────────────>│                         │
         │                        │                         │
         │                        │ 2. Route via WebSocket  │
         │                        │────────────────────────>│
         │                        │                         │
         │                        │              3. Capture screenshot
         │                        │                 of internal URL
         │                        │                         │
         │                        │ 4. Return image         │
         │                        │<────────────────────────│
         │                        │                         │
         │ 5. Screenshot response │                         │
         │<───────────────────────│                         │

The connector establishes an outbound WebSocket connection to Pixcap cloud. This means:

• No inbound firewall rules needed
• Works behind NAT and corporate firewalls
• Your internal URLs are never exposed to the internet

Docker Compose

version: '3.8'
services:
  pixcap-connector:
    image: dashah2/pixcap-connector:latest
    environment:
      - PIXCAP_CONNECTOR_TOKEN=${PIXCAP_CONNECTOR_TOKEN}
    restart: unless-stopped

Use Cases

• Internal Dashboards: Capture Grafana, Kibana, or custom dashboards
• Staging Environments: Screenshot staging sites before deployment
• CI/CD Integration: Generate visual diffs in your pipeline
• Private Applications: Document internal tools and wikis
• Monitoring: Periodic screenshots of internal services

Troubleshooting

Connector shows "Offline"

1. Check the connector is running: docker logs pixcap-connector
2. Verify your token is correct
3. Ensure outbound WebSocket connections are allowed (port 443)

Screenshots timeout

1. Increase SCREENSHOT_TIMEOUT environment variable
2. Check if the target URL is accessible from the connector host
3. Verify Chrome/Chromium is installed correctly

Browser launch fails

Set the Chrome path explicitly:

PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium docker run ...

Or on macOS:

PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Security

• Connector tokens are hashed (SHA-256) before storage
• All communication uses TLS encryption
• Tokens can be regenerated at any time from the dashboard
• Each connector has a unique ID for access control

Documentation

Full documentation: pixcap.dev/docs#connectors

Support

• Issues: github.com/dan-shah/pixcap/issues
• Email: [email protected]

License

MIT