Metadata-Version: 2.4
Name: telepy-cli
Version: 0.1.0
Summary: Standalone, split-tunnel Python client for UniFi Teleport (SSH/HTTP/SOCKS, no admin required)
Project-URL: Homepage, https://github.com/darki73/telepy-cli
Project-URL: Issues, https://github.com/darki73/telepy-cli/issues
Author: darki73
License: MIT License
        
        Copyright (c) 2026 darki73
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: nat-traversal,split-tunnel,ssh,teleport,ubiquiti,unifi,vpn,wireguard
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: awscrt>=0.20
Requires-Dist: awsiotsdk>=1.21
Requires-Dist: botocore>=1.34
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Requires-Dist: paramiko>=3.4
Description-Content-Type: text/markdown

# 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

```bash
# 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):

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

## Usage

```bash
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

```python
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/`](docs/README.md) directory explains, with genuine appreciation, **how
UniFi Teleport works** end to end - and how telepy speaks the same protocol:

- [Overview](docs/overview.md) - what Teleport is and why it's clever
- [Identity](docs/identity.md) · [Directory](docs/directory.md) ·
  [Signaling](docs/signaling.md) · [NAT traversal](docs/nat-traversal.md) ·
  [WireGuard data plane](docs/wireguard.md) · [Keepalive](docs/keepalive.md)
- [telepy architecture](docs/telepy-architecture.md) ·
  [Why split tunneling](docs/split-tunnel.md) ·
  [Good citizenship](docs/good-citizen.md)

## ⚠️ 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.)
