Metadata-Version: 2.4
Name: mihomo-py
Version: 0.2.1
Summary: A subscription and process manager for mihomo on Linux servers
Requires-Python: >=3.11
Requires-Dist: click<9,>=8.1
Requires-Dist: maxminddb<4,>=3
Requires-Dist: pyyaml<7,>=6
Requires-Dist: textual<9,>=8.2.8
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: playwright<2,>=1.56; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.4; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Requires-Dist: uv<1,>=0.7; extra == 'dev'
Provides-Extra: web
Requires-Dist: aiohttp<4,>=3.14.4; extra == 'web'
Requires-Dist: mihomo-py-web==0.2.1; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">

# mihomo-py

**Your server's proxies. One terminal.**

Subscriptions, nodes and logs — without leaving SSH.

[![PyPI](https://img.shields.io/pypi/v/mihomo-py?color=8bbbc5)](https://pypi.org/project/mihomo-py/)
[![Python](https://img.shields.io/badge/Python-3.11%2B-8bbbc5)](https://pypi.org/project/mihomo-py/)
![Platform](https://img.shields.io/badge/Linux-x86__64%20%7C%20aarch64-a3afc2)

[English](README.md) · [简体中文](README.zh-CN.md)

</div>

![TUI: subscriptions, core controls and server status](docs/assets/tui-subscriptions.en.png)

A [mihomo](https://github.com/MetaCubeX/mihomo) client for Linux servers. Add a subscription, start the core, and manage it with your mouse or keyboard. The core and default GEO databases ship with the package.

The TUI screenshots show v0.1.5 in English at 100 × 32. Use the language button to switch between English and Chinese.

## Install. Open. Done.

```bash
python -m pip install mihomo-py
mihomo-py
```

Requires **Python 3.11+**, **Linux kernel 5.3+** with pidfd support, and **x86_64 / aarch64**. Works with system Python and Conda. Recommended terminal size: **80 × 24** or larger. The TUI follows the system language on first launch and supports Chinese and English; use the language button to switch between Follow system, Chinese, and English.

1. Click **Add**, or press `Ctrl+A`. Enter a name and a subscription URL or local YAML path.
2. Single-click to browse a subscription; double-click or press `Enter` to use it.
3. Click **Start**. Your HTTP/SOCKS proxy is ready at `127.0.0.1:7897` by default.

Subscriptions must be complete Clash/mihomo YAML configurations. Base64 node lists and individual proxy links are not supported.

## Find a node. Switch. Test.

![TUI: proxy groups, node selection and latency testing](docs/assets/tui-nodes.en.png)

Press `2` for nodes, select a proxy group, and press `/` to search. In a manual group, `Enter` switches the selected node immediately; **Test latency** measures one node. Node choices survive core restarts.

## Follow logs. Keep your place.

![TUI: live logs with pause and resume controls](docs/assets/tui-logs.en.png)

Press `3` for logs. Scroll up to pause; press `End` to resume following. Press `q` to leave the TUI — **the core keeps running**.

`1 / 2 / 3` switch tabs · `i` opens details · `?` shows shortcuts. [Full TUI guide →](docs/tui.en.md)

## Prefer a browser?

![Web: subscription management using the same configuration as the TUI](docs/assets/web-subscriptions.png)

Install the optional Web resources with `python -m pip install 'mihomo-py[web]'`, then click **Enable Web** in the TUI. The gateway runs as a separate service on port `9091` by default, uses the configured management bind address, and stays running after the TUI exits. Click **Web** for the address and login key; **Settings** can rotate the shared login key. The same gateway manages subscriptions and embeds the node dashboard. [Setup →](docs/cli.en.md#web-access)

## Shell proxy and local TUN

```bash
mihomo-py proxy run -- curl https://example.com
eval "$(mihomo-py proxy env --shell bash)"
```

`proxy run` works with programs that honor proxy environment variables. Use `proxy env --unset --shell bash` to output cleanup commands. For local traffic interception, start `mihomo-py --sudo`, enter your sudo password, and enable TUN in Settings. CLI users can run `mihomo-py --sudo tun doctor`, then `mihomo-py --sudo tun enable`. TUN requires Linux, iproute2, CAP_NET_ADMIN and `/dev/net/tun`; it may interrupt SSH and connectivity when proxies fail. Inspect with `tun status`, disable with `tun disable`. No automatic privilege elevation, firewall changes or Shell startup file edits. [Configuration and recovery →](docs/cli.en.md#shell-proxy-and-tun)

## Go further

[CLI & scripting](docs/cli.en.md) · [TUI guide](docs/tui.en.md) · [Documentation](docs/README.md) · [Offline installation](docs/packaging.md)

The proxy listens on `127.0.0.1:7897` by default. The authenticated management API listens on `0.0.0.0:9090`; the optional Web gateway listens on `0.0.0.0:9091`. Use a trusted network or change the bind address in **Settings**. Linux local TUN is explicitly opt-in and disabled by default. Shell proxy environment output and command wrapping are available; privileges are never elevated automatically.

*TUI screenshots render the current application with fixed demo data (including sample logs and latency), without real subscription credentials. The Web screenshot uses an isolated local instance. Bundled resources retain their [upstream notices](src/mihomo_py/_vendor/NOTICE.txt).*
