Wyndo Documentation

Complete guide to setting up and running Wyndo tunnels

Getting Started

Wyndo allows you to expose your local development server to the internet through secure tunnels. This guide will walk you through installation, basic usage, and production deployment patterns.

Installation

Download the Wyndo client for your platform from the downloads page (requires login).

macOS

# Extract the archive
tar -xzf wyndo-macos-*.tar.gz

# Make executable
chmod +x wyndo

# Move to PATH (optional but recommended)
sudo mv wyndo /usr/local/bin/wyndo

# Verify installation
wyndo --version

Linux

# Extract the archive
tar -xzf wyndo-linux-*.tar.gz

# Make executable
chmod +x wyndo

# Move to PATH
sudo mv wyndo /usr/local/bin/wyndo

# Verify installation
wyndo --version

Windows

# Extract the ZIP file to a folder (e.g., C:\wyndo)

# Add to PATH (optional):
# 1. Open System Properties > Environment Variables
# 2. Edit the "Path" variable
# 3. Add the folder containing wyndo.exe

# Or run directly:
.\wyndo.exe --version

Basic Usage

Before starting a tunnel, you'll need an API token from your API Tokens page.

Starting a Tunnel

# Basic HTTP/HTTPS tunnel to local port
wyndo --into-port 3000 --token YOUR_TOKEN

# With a custom name (for easier identification)
wyndo --into-port 3000 --token YOUR_TOKEN --name my-api

# Using environment variable for token
export WYNDO_TOKEN=your_token_here
wyndo --into-port 3000

TCP Tunnels

For raw TCP tunneling (databases, SSH, custom protocols):

# Start TCP tunnel
wyndo --into-port 5432 --token YOUR_TOKEN --tcp

# With a custom name
wyndo --into-port 5432 --token YOUR_TOKEN --name postgres --tcp

Command Line Options

Option Description Required
--into-port Local port to tunnel Yes
--token API authentication token Yes (or use WYNDO_TOKEN env var)
--name Custom tunnel name No
--tcp Enable TCP tunnel mode (default is HTTP/HTTPS) No

Running as a Service

For production environments, you'll want Wyndo to start automatically and restart on failures.

macOS (launchd)

Create a Launch Agent to run Wyndo automatically.

1. Create the plist file

sudo nano ~/Library/LaunchAgents/com.wyndo.tunnel.plist

2. Add the following configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.wyndo.tunnel</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/wyndo</string>
        <string>--into-port</string>
        <string>3000</string>
        <string>--token</string>
        <string>YOUR_TOKEN_HERE</string>
        <string>--name</string>
        <string>my-service</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/tmp/wyndo.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/wyndo.error.log</string>
</dict>
</plist>

3. Load and start the service

# Load the service
launchctl load ~/Library/LaunchAgents/com.wyndo.tunnel.plist

# Start the service
launchctl start com.wyndo.tunnel

# Check status
launchctl list | grep wyndo

# View logs
tail -f /tmp/wyndo.log

# Stop the service
launchctl stop com.wyndo.tunnel

# Unload the service
launchctl unload ~/Library/LaunchAgents/com.wyndo.tunnel.plist

Linux (systemd)

Create a systemd service for automatic startup and monitoring.

1. Create the service file

sudo nano /etc/systemd/system/wyndo.service

2. Add the following configuration

[Unit]
Description=Wyndo Tunnel Service
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME
ExecStart=/usr/local/bin/wyndo --into-port 3000 --token YOUR_TOKEN --name my-service
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

3. Enable and start the service

# Reload systemd
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable wyndo

# Start the service
sudo systemctl start wyndo

# Check status
sudo systemctl status wyndo

# View logs
sudo journalctl -u wyndo -f

# Restart the service
sudo systemctl restart wyndo

# Stop the service
sudo systemctl stop wyndo

Using Environment Variables (Recommended)

Store your token in an environment file for better security:

# Create environment file
sudo nano /etc/wyndo/wyndo.env

# Add your token
WYNDO_TOKEN=your_token_here

# Update service file
[Service]
EnvironmentFile=/etc/wyndo/wyndo.env
ExecStart=/usr/local/bin/wyndo --into-port 3000 --name my-service

# Protect the file
sudo chmod 600 /etc/wyndo/wyndo.env

Windows Service

Use NSSM (Non-Sucking Service Manager) to run Wyndo as a Windows service.

1. Install NSSM

# Using Chocolatey
choco install nssm

# Or download from: https://nssm.cc/download

2. Install the service

# Open PowerShell as Administrator
nssm install WyndoTunnel "C:\wyndo\wyndo.exe"

# Set arguments
nssm set WyndoTunnel AppParameters "--into-port 3000 --token YOUR_TOKEN --name my-service"

# Set working directory
nssm set WyndoTunnel AppDirectory "C:\wyndo"

# Configure auto-restart
nssm set WyndoTunnel AppRestartDelay 10000

# Set output logging
nssm set WyndoTunnel AppStdout "C:\wyndo\logs\stdout.log"
nssm set WyndoTunnel AppStderr "C:\wyndo\logs\stderr.log"

# Start the service
nssm start WyndoTunnel

3. Manage the service

# Check status
nssm status WyndoTunnel

# Stop the service
nssm stop WyndoTunnel

# Restart the service
nssm restart WyndoTunnel

# Remove the service
nssm remove WyndoTunnel confirm

# Or use Windows Services
services.msc

Alternative: Task Scheduler

For simpler setups, use Windows Task Scheduler:

  1. Open Task Scheduler
  2. Create Basic Task → Name: "Wyndo Tunnel"
  3. Trigger: "When the computer starts"
  4. Action: "Start a program"
  5. Program: C:\wyndo\wyndo.exe
  6. Arguments: --into-port 3000 --token YOUR_TOKEN
  7. Properties → Conditions → Uncheck "Start only if on AC power"
  8. Properties → Settings → Check "If task fails, restart every: 10 minutes"

Best Practices

Security

  • Protect Your Tokens: Never commit API tokens to version control. Use environment variables or secure secret management.
  • Limit Token Scope: Create separate tokens for different environments (dev, staging, production).
  • Rotate Tokens: Regularly rotate API tokens and revoke unused ones from the tokens page.
  • Use Named Tunnels: Give tunnels descriptive names to easily identify and manage them.

Reliability

  • Auto-Restart: Always configure automatic restart on failure (systemd, launchd, or NSSM).
  • Monitoring: Set up log monitoring and alerts for tunnel disconnections.
  • Health Checks: Implement application-level health checks to verify tunnel connectivity.
  • Graceful Shutdown: Use SIGTERM signals for graceful shutdown during deployments.

Performance

  • Network Location: Run tunnels geographically close to your application server.
  • Resource Limits: Set appropriate memory and CPU limits for tunnel processes.
  • Connection Pooling: Ensure your application handles keep-alive connections properly.

Logging

  • Structured Logs: Configure log rotation to prevent disk space issues.
  • Log Levels: Use appropriate verbosity for production environments.
  • Centralized Logging: Ship logs to a centralized logging system (CloudWatch, Datadog, etc.).

Troubleshooting

Connection Issues

Error: "Failed to connect to server"

  • Check your internet connection
  • Verify the server address is correct
  • Ensure firewall isn't blocking outbound connections to ports 4040 or 5050
  • Try using a different network

Error: "Authentication failed"

  • Verify your API token is correct
  • Check if the token has been revoked on the tokens page
  • Ensure there are no extra spaces in the token
  • Generate a new token if needed

Tunnel Disconnects Frequently

  • Check your network stability
  • Verify the local service is running on the specified port
  • Review system logs for errors
  • Ensure auto-restart is configured properly

Service Issues

macOS: Service Won't Start

# Check launchd logs
log show --predicate 'subsystem == "com.apple.launchd"' --last 1h | grep wyndo

# Verify plist syntax
plutil -lint ~/Library/LaunchAgents/com.wyndo.tunnel.plist

# Check file permissions
ls -la ~/Library/LaunchAgents/com.wyndo.tunnel.plist

Linux: Service Fails to Start

# Check service status
sudo systemctl status wyndo

# View detailed logs
sudo journalctl -u wyndo -n 50

# Verify service file syntax
sudo systemd-analyze verify wyndo.service

# Check file permissions
sudo ls -la /etc/systemd/system/wyndo.service

Windows: Service Won't Start

  • Check Event Viewer → Windows Logs → Application
  • Verify the path to wyndo.exe is correct
  • Check NSSM service configuration: nssm edit WyndoTunnel
  • Ensure the service has proper permissions

Getting Help

If you're still experiencing issues:

  • Check the contact page for support options
  • Include relevant log files when reporting issues
  • Provide your operating system and Wyndo version