techthinkerorg/telepath

By techthinkerorg

•Updated 2 months ago

Source repository: https://github.com/tech-thinker/telepath

Image

Networking

Internet of things

Developer tools

354

Overview Tags

techthinkerorg/telepath repository overview

⁠telepath

GitHub release (latest by date) GitHub Workflow Status GitHub GitHub All Releases GitHub last commit GitHub forks GitHub top language

Telepath is a modern, intelligent CLI tool for seamless and secure port forwarding. Designed with versatility and ease of use in mind, Telepath enables developers and system administrators to create complex forwarding paths across multiple hosts effortlessly. Whether you're working with password-based or keyfile authentication, single or multiple jump hosts, Telepath has you covered.

⁠Why Choose Telepath?

Multi-Jump Host Support: Telepath allows seamless port forwarding through multiple intermediate hosts, making it ideal for accessing restricted networks.
Secure Authentication: Supports password-based and keyfile authentication, ensuring flexibility and security.
CLI Simplicity: Its intuitive command-line interface simplifies complex operations with straightforward commands.
Daemon Mode: Runs as a background service for continuous operation, perfect for long-running port-forwarding tasks.
Customizable & Open Source: It's open source and developer-friendly, so you can tweak it for your needs.

⁠Installation

Download and install executable binary from GitHub releases page.

⁠Using homebrew

brew tap tech-thinker/tap
brew install telepath

⁠Linux Installation

# Use latest tag name from release page
TAG=<tag-name>

curl -sL "https://github.com/tech-thinker/telepath/releases/download/${TAG}/telepath-linux-amd64" -o telepath
chmod +x telepath
sudo mv telepath /usr/bin

⁠MacOS Installation

# Use latest tag name from release page
TAG=<tag-name>

curl -sL "https://github.com/tech-thinker/telepath/releases/download/${TAG}/telepath-darwin-amd64" -o telepath
chmod +x telepath
sudo mv telepath /usr/bin

⁠Windows Installation

# Use latest tag name from release page
TAG=<tag-name>

curl -sL "https://github.com/tech-thinker/telepath/releases/download/${TAG}/telepath-windows-amd64.exe" -o telepath.exe
telepath.exe

⁠Verify checksum

# Use latest tag name from release page
TAG=<tag-name>

# Using sha256sum
curl -sL "https://github.com/tech-thinker/telepath/releases/download/${TAG}/checksum-sha256sum.txt" -o checksum-sha256sum.txt
sha256sum --ignore-missing --check checksum-sha256sum.txt

# Using md5sum
curl -sL "https://github.com/tech-thinker/telepath/releases/download/${TAG}/checksum-md5sum.txt" -o checksum-md5sum.txt
md5sum --ignore-missing --check checksum-md5sum.txt

Output:

telepath-darwin-amd64: OK
telepath-darwin-amd64.tar.gz: OK
telepath-darwin-arm64: OK
telepath-darwin-arm64.tar.gz: OK
telepath-linux-amd64: OK
telepath-linux-amd64.tar.gz: OK
telepath-linux-arm: OK
telepath-linux-arm.tar.gz: OK
telepath-linux-arm64: OK
telepath-linux-arm64.tar.gz: OK
telepath-windows-amd64.exe: OK
telepath-windows-i386.exe: OK

⁠CLI Guide

telepath help

telepath -h

Start tunnel using cli

telepath -f /etc/telepath/telepath.json

Test tunnel configuration

telepath -f /etc/telepath/telepath.json --dry-run

⁠Run using Docker compose

You can run using docker compose and use it's internal network to access it.

services:
  telepath:
    container_name: telepath
    image: ghcr.io/tech-thinker/telepath:latest
    networks:
      - telepath
    volumes:
      - ./myconfig:/etc/telepath

networks:
  telepath:

⁠Define Config file

The configuration file is a JSON array of objects. Each object defines a tunnel.

[
  {
    "name": "mongodb",
    "type": "L",
    "localPort": 27017,
    "localHost": "0.0.0.0",
    "remotePort": 27017,
    "remoteHost": "0.0.0.0",
    "server": {
      "host": "final-host-ip",
      "port": 22,
      "username": "user",
      "authType": "KEY",
      "password": "",
      "key": "/etc/autossh/id_rsa",
      "passphrase": "passphrase-base64",
      "jump": {
        "host": "jump-1-ip",
        "port": 22,
        "username": "user",
        "authType": "KEY",
        "password": "",
        "key": "/etc/autossh/id_rsa",
        "passphrase": "passphrase-base64",
        "jump": {
          "host": "jump-2-ip",
          "port": 22,
          "username": "user",
          "authType": "PASS",
          "password": "password-base64"
        }
      }
    }
  }
]

⁠Fields Description

Field	Type	Required	Description
`name`	string	✅	Identifier for the tunnel.
`type`	string	✅	Tunnel type: `L` for remote → local, `R` for local → remote.
`localPort`	number	✅	Port on the local machine.
`localHost`	string	✅	Local host IP or `0.0.0.0` to bind all interfaces.
`remotePort`	number	✅	Port on the remote machine.
`remoteHost`	string	✅	Remote host IP or `0.0.0.0`.
`server`	object	✅	Final destination SSH server configuration.
`server.host`	string	✅	SSH server IP or hostname.
`server.port`	number	✅	SSH server port, usually 22.
`server.username`	string	✅	SSH username.
`server.authType`	string	✅	Authentication type: `KEY` or `PASS`.
`server.key`	string	🔹	Path to SSH key file if `authType` is `KEY`.
`server.password`	string	🔹	Password if `authType` is `PASS`.
`server.passphrase`	string	🔹	Passphrase for the SSH key if required.
`server.jump`	object/null	-	Optional jump host configuration (recursive structure).

Note: Jump hosts are optional and can be nested multiple times.

⁠Tunnel Type

L (Local): Forwards traffic from remote → local
R (Remote): Forwards traffic from local → remote

⁠Example Topology Diagram

ExampleTopologyDiagram

A: Your local machine
J2, J1: Intermediate jump hosts
S: Final SSH server
M: MongoDB service running on the remote host

⁠Simple Tunnel Diagram (No Jump Hosts)

SimpleTunnelDiagram

L: Local machine
F: Final SSH server
D: Remote service (MongoDB, PostgreSQL, etc.)

⁠Authentication Flow

Password and Passphrase should be in base64 encoded.

KEY authentication
- Uses a private key (key) and optional passphrase.
Password authentication
- Uses password field directly.

AuthenticationFlow

⁠Usage Notes

You can have multiple tunnels defined in the JSON array.
Jump hosts can be nested arbitrarily.
Each tunnel should have a unique name.
All ports and hosts are configurable to support complex network setups.

Tag summary

Recent tags

Content type

Image

Digest

sha256:d3fcf8907…

Size

32.6 MB

Last updated

2 months ago

docker pull techthinkerorg/telepath:v2.1.0