wild-pc/devbox-connect/README.md

devbox-connect

SSH tunnel manager for connecting local ports to your devbox.

Features

• Simple YAML configuration - Define tunnels in a readable config file
• Auto-reconnect - Automatically reconnects with exponential backoff when connections drop
• Multiple tunnels - Manage many port forwards to one or more hosts
• Windows service support - Run as a background service with auto-start

Installation

# Install with uv
uv tool install git+https://github.com/YOUR_USERNAME/devbox-connect

# Or install from local directory
cd devbox-connect
uv tool install .

Quick Start

1. Create a configuration file tunnels.yaml:

user: your-username
key_file: ~/.ssh/id_rsa

tunnels:
  - name: web-dev
    host: devbox.example.com
    remote_port: 8080

  - name: database
    host: devbox.example.com
    remote_port: 5432

2. Start the tunnels:

devbox-connect -c tunnels.yaml start

3. Access your devbox services locally:
   • localhost:8080 → devbox:8080
   • localhost:5432 → devbox:5432

Usage

devbox-connect [-c CONFIG] COMMAND

Commands:
  start      Start tunnels and keep running (default)
  status     Show configured tunnels
  validate   Validate configuration file

Options:
  -c, --config PATH    Path to config file (default: tunnels.yaml)
  -v, --verbose        Enable verbose output

Configuration

See tunnels.example.yaml for a complete example.

Simple Format (single host)

user: username
key_file: ~/.ssh/id_rsa  # Optional

tunnels:
  - name: web
    host: devbox.example.com
    remote_port: 8080
    local_port: 8080      # Optional, defaults to remote_port

  - name: jupyter
    host: devbox.example.com
    remote_port: 8888
    local_port: 9999      # Use different local port

Grouped Format (multiple hosts)

hosts:
  - host: devbox1.example.com
    user: username
    tunnels:
      - name: web
        remote_port: 8080

  - host: devbox2.example.com
    user: username
    tunnels:
      - name: api
        remote_port: 3000

Configuration Options

Option	Description	Default
user	SSH username	(required)
host	Remote hostname	(required)
key_file	Path to SSH private key	SSH agent/default
remote_port	Port on remote host	(required)
local_port	Local port to listen on	Same as remote_port
remote_host	Host on remote side	localhost
reconnect_delay	Initial reconnect delay (seconds)	5
max_reconnect_delay	Max reconnect delay	60

Forwarding Through Devbox

You can access services on other hosts through your devbox:

tunnels:
  - name: internal-db
    host: devbox.example.com
    remote_port: 5432
    remote_host: internal-db.corp  # Accessed via devbox

Windows Service

To run devbox-connect as a Windows service that starts automatically:

Prerequisites

1. Install NSSM (Non-Sucking Service Manager):

   winget install nssm
   

2. Install devbox-connect:

   uv tool install .
   

Install Service

Run PowerShell as Administrator:

.\service\install-service.ps1 -ConfigPath C:\path\to\tunnels.yaml

Manage Service

# Check status
Get-Service DevboxConnect

# Start/Stop
Start-Service DevboxConnect
Stop-Service DevboxConnect

# View logs
Get-Content $env:LOCALAPPDATA\devbox-connect\service.log -Tail 50

# Uninstall
.\service\install-service.ps1 -Uninstall

Manual Run (without service)

service\run-manual.bat C:\path\to\tunnels.yaml

SSH Key Setup

devbox-connect uses SSH key authentication. Ensure your key is set up:

1. Generate a key (if needed):

   ssh-keygen -t ed25519 -f ~/.ssh/devbox_key
   

2. Copy to devbox:

   ssh-copy-id -i ~/.ssh/devbox_key user@devbox.example.com
   

3. Reference in config:

   key_file: ~/.ssh/devbox_key
   

Or use SSH agent (key_file not needed if agent has your key loaded).

Troubleshooting

Connection refused

• Check the remote service is running on the specified port
• Verify you can SSH to the host manually: ssh user@devbox

Permission denied

• Check your SSH key is correct and has proper permissions
• On Windows, ensure key file isn't world-readable

Port already in use

• Change local_port to an unused port
• Check what's using the port: netstat -an | findstr :8080

Tunnels disconnect frequently

• Check network stability
• Increase reconnect_delay and max_reconnect_delay
• Some networks/firewalls drop idle connections; the remote service may need keepalive

License

MIT