A minimal macOS TUI (Terminal User Interface) application for managing SSH SOCKS proxy tunnels.
- Terminal-based UI - Clean, keyboard-driven interface using Ratatui
- List configured remote servers in a scrollable table
- Add, edit, and delete server configurations
- Connect/disconnect from servers with keyboard shortcuts
- Real-time connection stats - Duration, latency, active connections, and traffic monitoring
- Automatic SOCKS proxy configuration via macOS network settings
- SSH agent and key-based authentication support
- Comprehensive logging for debugging
Clone or download this repository to something like ~/Code/chaussettes
Install dependencies:
cd ~/Code/chaussettes
bundle install./bin/chaussettesYou can add the executable to your PATH to run it from anywhere.
- Ensure you have SSH keys set up in
~/.ssh/or use SSH agent - The app will create
~/.config/chaussettes/for storing server configurations - Logs are written to
~/.local/share/chaussettes/logs/chaussettes.log
- Press
ato open the add server form - Fill in the details:
- Alias (optional): A friendly name for the server
- Host*: The server hostname or IP address
- User*: Your SSH username
- SSH Port*: Usually 22 (can be customized)
- SOCKS Port*: The local port for the proxy (default: 1080)
- Key Path (optional): Path to your SSH private key (uses SSH agent if not specified)
- Select a server using
↑/↓arrow keys - Press
cto connect - The app will:
- Establish an SSH tunnel with dynamic port forwarding (
ssh -D) - Enable the SOCKS proxy in macOS network settings
- Establish an SSH tunnel with dynamic port forwarding (
- Status will show as "● Connected" when successful
- A Connection Stats panel appears at the top showing:
- Server name and SOCKS port
- External connection info - Shows your public IP, hostname, location, ISP, and timezone via ipinfo.io (updated every 30s)
- Connection duration (HH:MM:SS format)
- Latency to remote server (ping time in ms)
- Active connections count
- Data transferred (bytes sent/received)
- Transfer rate with ASCII sparkline showing 2 minutes of traffic history
- Press
xto disconnect - The app will:
- Close the SSH tunnel
- Disable the SOCKS proxy in macOS network settings
Stored in:
~/.config/chaussettes/servers.yml
This file is automatically managed by the application.
When connected to a server, the application displays real-time statistics:
Connection Duration: Tracks how long you've been connected (updated every frame)
External Connection Info: Fetches and displays your public connection details from ipinfo.io every 30 seconds:
- IP Address: Your public IPv4 address (e.g., "78.192.193.72")
- Hostname: Reverse DNS hostname (e.g., "mil75-5-78-192-193-72.fbxo.proxad.net")
- Country Code: ISO country code (e.g., "FR")
- Location: City, region, and country (e.g., "Paris, Île-de-France, FR")
- ISP: Your internet service provider name (e.g., "Free SAS")
- Timezone: Your timezone (e.g., "Europe/Paris")
This helps verify that your SOCKS proxy is working correctly and shows what IP address and location you're appearing as to the outside world.
Latency Monitoring: Background thread pings the remote server every 1 second to measure round-trip time
Traffic Monitoring: Monitors network activity through the SOCKS proxy:
- Active Connections: Number of active TCP connections through the SSH tunnel (updated every 1 second via
lsof) - Data Transferred: Tracks bytes sent and received through the loopback interface (updated every 1 second via
netstat) - Transfer Rate & Sparkline: Shows current transfer speed with an ASCII sparkline (▁▂▃▄▅▆▇█) visualizing the last 2 minutes of traffic history (120 samples at 1-second intervals). This gives you a quick visual indication of traffic patterns and throughput over time.
- Stats are shown in human-readable format (B, KB, MB, GB)
The stats panel appears automatically at the top of the screen when connected and disappears when disconnected.
Application logs are stored in:
~/.local/share/chaussettes/logs/chaussettes.log
Logs include:
- Connection attempts and results
- SSH authentication details
- Proxy configuration changes
- Error messages with stack traces
View logs in real-time:
tail -f ~/.local/share/chaussettes/logs/chaussettes.log- macOS (uses
networksetupandsshcommands) - Ruby 3.4+
- SSH client (system
sshcommand) - SSH keys configured on remote servers or SSH agent running
- Admin privileges may be required for changing network proxy settings
Run the test suite:
bundle exec rspecchaussettes/
├── bin/chaussettes # Executable entry point
├── lib/
│ ├── chaussettes.rb # Main module
│ ├── models/
│ │ └── server.rb # Server configuration model
│ ├── services/
│ │ ├── config_store.rb # YAML persistence
│ │ ├── logger.rb # Logging service
│ │ ├── proxy_manager.rb # macOS proxy settings
│ │ └── ssh_tunnel.rb # SSH connection management
│ └── ui/
│ └── tui_app.rb # Ratatui TUI application
└── spec/ # Test suite
Check the logs for detailed error messages:
cat ~/.local/share/chaussettes/logs/chaussettes.logCommon issues:
- Authentication failed: Ensure your SSH key is loaded in the agent or specify the correct key path
- Host key mismatch: The app automatically accepts new host keys. If a host key changes, restart the app
- DNS resolution failed: Check that the hostname is correct and reachable
- Check that the SOCKS proxy is enabled in System Preferences > Network
- Verify the proxy port matches what you configured (default: 1080)
- Check logs for proxy configuration errors
The app automatically detects your primary network interface by:
- Checking the default route interface
- Finding the first active (non-VPN) interface with an IP address
- Falling back to "Wi-Fi" if detection fails
If proxy settings aren't applying, check that the detected interface in the logs matches your active connection.
MIT