telepy-cli 0.1.0

Standalone, split-tunnel Python client for UniFi Teleport (SSH/HTTP/SOCKS, no admin required)

telepy

A standalone, split-tunnel UniFi Teleport client - in pure Python.

telepy connects to your UniFi consoles over Teleport (the same NAT-traversed WireGuard path the official WiFiman app uses) and lets you SSH in, hit the local web UI/API, or proxy traffic to the LAN - without routing your whole machine through the remote site. Only the subnets you choose go over the tunnel; everything else stays on your normal connection.

No kernel WireGuard. No bundled binaries. No admin required for the everyday commands. Works where a self-hosted VPN can't (the official Teleport relay does the NAT traversal for you).

Built because WiFiman is full-tunnel only: the moment you connect, all your traffic goes through the remote console and you lose everything else - your other networks, your video call, the SSH session you were already in. telepy routes only what you ask it to.

---

Why

• Split tunnel. Reach 10.13.0.1 on a remote console while your internet, LAN, and existing sessions stay exactly where they are.
• No admin for daily use. ssh, http, and proxy run entirely in userspace (a small WireGuard + TCP/IP stack) - no network adapter, no routes, no root.
• Scriptable. A clean Python API for automation: with telepy.open(name) as t: t.ssh("uptime").
• Cross-platform. Linux, macOS, Windows. Great on a headless box.
• Standalone. Doesn't need WiFiman installed; logs in with your UI account.

Install

# recommended for the CLI — isolated, puts the `telepy` command on your PATH:
uv tool install telepy-cli      # or:  pipx install telepy-cli

# or into the current environment (e.g. to use telepy as a library):
pip install telepy-cli

# or run it once without installing:
uvx --from telepy-cli telepy ls

The bare name telepy was already taken on PyPI, so the distribution is telepy-cli, while the installed command and the Python import are both telepy.

Requires Python 3.11+. First run, authenticate once (cached for later, including headless):

telepy login                # UI SSO + MFA (push "Yes, that's me" or a 6-digit code)

Usage

telepy ls                   # list your consoles

# userspace, no admin:
telepy ssh                  # pick a console, then host/user/password -> a shell
telepy ssh "My Console" --host 10.13.0.1 -- "uptime"     # one-off command
telepy http https://10.13.0.1/ --console "My Console"    # one-off HTTP(S) to the LAN
telepy proxy "My Console"   # local SOCKS5 (point your browser at 127.0.0.1:1080)

# system-wide TUN, needs admin/root:
sudo telepy tunnel "My Console"          # split: route only the safe subnets
sudo telepy tunnel "My Console" --full   # route ALL traffic (like WiFiman)

Omit the console name and telepy lists them interactively, automatically hiding the console you're physically behind.

As a library

from telepy import Telepy

tp = Telepy()
with tp.open("My Console") as t:           # userspace, no admin
    rc, out, err = t.ssh("uptime", host="10.13.0.1")
    sock = t.dial("192.168.1.1", 443)      # raw TCP to a LAN host
    status, headers, body = t.request("https://10.13.0.1/")
    srv = t.serve_socks(port=1080)         # local SOCKS5 over the tunnel

Two modes

	ssh / http / proxy	tunnel
Mechanism	userspace WireGuard + TCP/IP stack	OS TUN device + routes
Admin/root	no	yes
Scope	per-connection (you choose targets)	system-wide (any app)
Best for	automation, headless boxes, quick access	"make this machine feel on the LAN"

How it works

telepy is a clean-room reimplementation of the Teleport client protocol, built by observing my own network traffic, to consoles I administer, with my own credentials - no decompilation, no proprietary code, no DRM circumvention. It speaks the same wire formats the official client does:

1. UI SSO login (+MFA) → short-lived cloud credentials.
2. Cloud directory of your consoles and their LAN subnets.
3. Teleport signaling (AWS IoT MQTT + cloud HTTPS) to exchange keys + ICE candidates.
4. ICE/STUN NAT traversal, then a from-scratch WireGuard data plane (Noise handshake + ChaCha20-Poly1305 transport + rekey).
5. A small userspace TCP/IP stack (with userspace TLS) for the no-admin path, or a TUN device for the system-wide path.

It deliberately routes only the subnets you select - subtracting the subnets of the site you're currently behind so local and remote addresses never collide.

Documentation

The docs/ directory explains, with genuine appreciation, how UniFi Teleport works end to end - and how telepy speaks the same protocol:

• Overview - what Teleport is and why it's clever
• Identity · Directory · Signaling · NAT traversal · WireGuard data plane · Keepalive
• telepy architecture · Why split tunneling · Good citizenship

⚠️ Disclaimer

telepy is an independent, unofficial interoperability project. It is not affiliated with, authorized, or endorsed by Ubiquiti Inc. "UniFi", "WiFiman", and "Teleport" are trademarks of Ubiquiti Inc., used here only to describe what this software interoperates with.

Use it only with consoles you own or administer, and with your own account. Doing so may violate Ubiquiti's Terms of Service / EULA; that's between you and Ubiquiti. This software is provided as-is, with no warranty - it can change network routing and you use it entirely at your own risk.

No Ubiquiti code, binaries, or assets are included in this repository.

💌 A note to Ubiquiti

I genuinely love your gear - the hardware is gorgeous, the ecosystem is a joy, and Teleport's zero-config NAT traversal is honestly magic. This whole project exists for one reason:

Please, just add split tunneling to WiFiman. 🙏

That's it. That's the feature. The moment WiFiman lets me route a couple of subnets instead of my entire machine, I will happily archive this repo and go back to clicking your lovely button. Until then - here's a polite, clean-room, bring-your-own-credentials way to have it both ways.

(And if you'd rather I take this down, reach out - I'd much rather have the feature than the repo.)