usmo 0.6.2__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. {usmo-0.6.2 → usmo-0.7.0}/PKG-INFO +3 -1
  2. {usmo-0.6.2 → usmo-0.7.0}/README.md +2 -0
  3. usmo-0.7.0/docs/commands/clash.md +208 -0
  4. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/index.md +2 -0
  5. usmo-0.7.0/docs/commands/proxy.md +213 -0
  6. {usmo-0.6.2 → usmo-0.7.0}/docs/index.md +2 -0
  7. {usmo-0.6.2 → usmo-0.7.0}/mkdocs.yml +2 -0
  8. {usmo-0.6.2 → usmo-0.7.0}/scripts/_config.json +25 -2
  9. usmo-0.7.0/scripts/clash.py +1499 -0
  10. usmo-0.7.0/scripts/proxy.py +1140 -0
  11. {usmo-0.6.2 → usmo-0.7.0}/scripts/serve.py +4 -4
  12. {usmo-0.6.2 → usmo-0.7.0}/src/usmo/_version.py +2 -2
  13. {usmo-0.6.2 → usmo-0.7.0}/.github/workflows/docs.yml +0 -0
  14. {usmo-0.6.2 → usmo-0.7.0}/.github/workflows/release.yml +0 -0
  15. {usmo-0.6.2 → usmo-0.7.0}/.gitignore +0 -0
  16. {usmo-0.6.2 → usmo-0.7.0}/.pre-commit-config.yaml +0 -0
  17. {usmo-0.6.2 → usmo-0.7.0}/dev/bump_version.py +0 -0
  18. {usmo-0.6.2 → usmo-0.7.0}/docs/architecture.md +0 -0
  19. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/bench.md +0 -0
  20. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/blobmount.md +0 -0
  21. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/builtin.md +0 -0
  22. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/clip.md +0 -0
  23. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/cp.md +0 -0
  24. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/cu122.md +0 -0
  25. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/gpu.md +0 -0
  26. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/init.md +0 -0
  27. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/inject-alias.md +0 -0
  28. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/notify.md +0 -0
  29. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/openai-proxy.md +0 -0
  30. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/port.md +0 -0
  31. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/rsync.md +0 -0
  32. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/secret.md +0 -0
  33. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/serve.md +0 -0
  34. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/share.md +0 -0
  35. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/sysinfo.md +0 -0
  36. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/tunnel.md +0 -0
  37. {usmo-0.6.2 → usmo-0.7.0}/docs/commands/wait.md +0 -0
  38. {usmo-0.6.2 → usmo-0.7.0}/docs/development.md +0 -0
  39. {usmo-0.6.2 → usmo-0.7.0}/docs/installation.md +0 -0
  40. {usmo-0.6.2 → usmo-0.7.0}/pyproject.toml +0 -0
  41. {usmo-0.6.2 → usmo-0.7.0}/scripts/bench.py +0 -0
  42. {usmo-0.6.2 → usmo-0.7.0}/scripts/blobmount.sh +0 -0
  43. {usmo-0.6.2 → usmo-0.7.0}/scripts/check_py.sh +0 -0
  44. {usmo-0.6.2 → usmo-0.7.0}/scripts/clip.py +0 -0
  45. {usmo-0.6.2 → usmo-0.7.0}/scripts/cp.py +0 -0
  46. {usmo-0.6.2 → usmo-0.7.0}/scripts/cu122.sh +0 -0
  47. {usmo-0.6.2 → usmo-0.7.0}/scripts/gpu.py +0 -0
  48. {usmo-0.6.2 → usmo-0.7.0}/scripts/init.sh +0 -0
  49. {usmo-0.6.2 → usmo-0.7.0}/scripts/inject_alias.py +0 -0
  50. {usmo-0.6.2 → usmo-0.7.0}/scripts/install.sh +0 -0
  51. {usmo-0.6.2 → usmo-0.7.0}/scripts/notify.py +0 -0
  52. {usmo-0.6.2 → usmo-0.7.0}/scripts/openai_proxy.py +0 -0
  53. {usmo-0.6.2 → usmo-0.7.0}/scripts/port.py +0 -0
  54. {usmo-0.6.2 → usmo-0.7.0}/scripts/rsync.py +0 -0
  55. {usmo-0.6.2 → usmo-0.7.0}/scripts/secret.py +0 -0
  56. {usmo-0.6.2 → usmo-0.7.0}/scripts/share.py +0 -0
  57. {usmo-0.6.2 → usmo-0.7.0}/scripts/sysinfo.sh +0 -0
  58. {usmo-0.6.2 → usmo-0.7.0}/scripts/tunnel.py +0 -0
  59. {usmo-0.6.2 → usmo-0.7.0}/scripts/wait.py +0 -0
  60. {usmo-0.6.2 → usmo-0.7.0}/src/usmo/__init__.py +0 -0
  61. {usmo-0.6.2 → usmo-0.7.0}/src/usmo/cli.py +0 -0
  62. {usmo-0.6.2 → usmo-0.7.0}/src/usmo/core.py +0 -0
  63. {usmo-0.6.2 → usmo-0.7.0}/tests/conftest.py +0 -0
  64. {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_autocheck.py +0 -0
  65. {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_hash.py +0 -0
  66. {usmo-0.6.2 → usmo-0.7.0}/tests/test_core_script.py +0 -0
  67. {usmo-0.6.2 → usmo-0.7.0}/tests/test_openai_proxy.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: usmo
3
- Version: 0.6.2
3
+ Version: 0.7.0
4
4
  Summary: Bootstrap machines and run cached utility scripts from one CLI.
5
5
  Project-URL: Homepage, https://github.com/HSPK/usm
6
6
  Project-URL: Repository, https://github.com/HSPK/usm
@@ -91,6 +91,8 @@ changes required.
91
91
  | `usm sysinfo` | Print system, GPU, CUDA, MPI, and distributed-ML environment summary. |
92
92
  | `usm inject-alias [--shell bash\|zsh\|powershell] [--file PATH]` | Insert or update the managed `usm` alias block in your shell rc file. |
93
93
  | `usm tunnel <local\|remote\|socks\|ls\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs>` | Start and manage SSH tunnels with persistent state; `enable`/`disable` install/remove a systemd `--user` unit for boot-time autostart. |
94
+ | `usm proxy <server\|client\|ls\|url\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs\|install>` | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy (`server`), or run a Clash client that routes rule-matched traffic through a remote proxy (`client`). Auto-installs `mihomo`; `enable`/`disable` manage a systemd `--user` unit. |
95
+ | `usm clash <sub\|use\|up\|down\|restart\|status\|mode\|proxies\|select\|test\|tun\|system-proxy\|lan\|logs\|conns\|dashboard\|enable\|disable\|install>` | ClashX-style CLI manager for the mihomo core: subscription/profile management, rule/global/direct mode, node selection, latency tests, TUN, system proxy, LAN sharing, live logs, and connection inspection. |
94
96
  | `usm gpu [free\|watch\|kill]` | GPU inventory, free-picker (`CUDA_VISIBLE_DEVICES=$(usm gpu free 2)`), live watch, kill CUDA processes. |
95
97
  | `usm port [PORT\|ls\|kill PORT]` | Show what's listening on a port; free a port by killing the holder. |
96
98
  | `usm notify [config\|test] [-- CMD ARGS]` | Wrap a command and ping ntfy.sh / Telegram / generic webhook when it exits. |
@@ -78,6 +78,8 @@ changes required.
78
78
  | `usm sysinfo` | Print system, GPU, CUDA, MPI, and distributed-ML environment summary. |
79
79
  | `usm inject-alias [--shell bash\|zsh\|powershell] [--file PATH]` | Insert or update the managed `usm` alias block in your shell rc file. |
80
80
  | `usm tunnel <local\|remote\|socks\|ls\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs>` | Start and manage SSH tunnels with persistent state; `enable`/`disable` install/remove a systemd `--user` unit for boot-time autostart. |
81
+ | `usm proxy <server\|client\|ls\|url\|stop\|start\|restart\|rm\|enable\|disable\|show\|logs\|install>` | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy (`server`), or run a Clash client that routes rule-matched traffic through a remote proxy (`client`). Auto-installs `mihomo`; `enable`/`disable` manage a systemd `--user` unit. |
82
+ | `usm clash <sub\|use\|up\|down\|restart\|status\|mode\|proxies\|select\|test\|tun\|system-proxy\|lan\|logs\|conns\|dashboard\|enable\|disable\|install>` | ClashX-style CLI manager for the mihomo core: subscription/profile management, rule/global/direct mode, node selection, latency tests, TUN, system proxy, LAN sharing, live logs, and connection inspection. |
81
83
  | `usm gpu [free\|watch\|kill]` | GPU inventory, free-picker (`CUDA_VISIBLE_DEVICES=$(usm gpu free 2)`), live watch, kill CUDA processes. |
82
84
  | `usm port [PORT\|ls\|kill PORT]` | Show what's listening on a port; free a port by killing the holder. |
83
85
  | `usm notify [config\|test] [-- CMD ARGS]` | Wrap a command and ping ntfy.sh / Telegram / generic webhook when it exits. |
@@ -0,0 +1,208 @@
1
+ # `usm clash`
2
+
3
+ A ClashX-style **command-line manager** for the [mihomo](https://github.com/MetaCubeX/mihomo)
4
+ (Clash.Meta) core: subscriptions, profile switching, rule/global/direct mode,
5
+ node selection, latency tests, TUN, system-proxy, LAN sharing, live logs and
6
+ traffic, and connection inspection — all from the terminal.
7
+
8
+ `usm clash` is the **client manager** (consume a subscription, route your
9
+ traffic out). For turning a box *into* a proxy, or a quick single-upstream
10
+ client, see [`usm proxy`](proxy.md).
11
+
12
+ The mihomo binary is auto-installed to `~/.cache/usm/bin/mihomo` on first use
13
+ (no sudo, no system packages); set `$USM_MIHOMO_BIN` to use your own.
14
+
15
+ ## Mental model
16
+
17
+ - **Profiles** — Clash configs, usually fetched from a **subscription** URL.
18
+ You can have many; one is **active**.
19
+ - **The core** — a single mihomo process driven by the active profile, with a
20
+ handful of manager-controlled overrides (port, mode, TUN, LAN, controller).
21
+ - **Runtime control** — once running, `usm clash` talks to mihomo's RESTful
22
+ API to switch mode, select nodes, test latency, stream logs, etc.
23
+
24
+ ```
25
+ subscription ─▶ profile (active) ─┐
26
+ ├─▶ runtime.yaml ─▶ mihomo ─▶ RESTful API ◀─ usm clash mode/select/test/logs
27
+ manager overrides (port/mode/tun)─┘ │
28
+ 127.0.0.1:7890 (http+socks) ◀─ your apps
29
+ ```
30
+
31
+ ## Subcommands
32
+
33
+ | Command | What it does |
34
+ | --- | --- |
35
+ | `sub add SOURCE [--name N] [--interval H]` | Add a subscription URL or a local config file. |
36
+ | `sub ls` | List profiles (active marker, type, last update, traffic, expiry). |
37
+ | `sub update [NAME]` | Re-fetch remote profiles (one or all). |
38
+ | `sub rm NAME` | Delete a profile. |
39
+ | `use NAME` | Set the active profile (hot-applies if running). |
40
+ | `up [NAME] [--tun] [--lan] [--system-proxy] [-p PORT]` | Start the core. |
41
+ | `down` | Stop the core (and restore system proxy). |
42
+ | `restart` | Restart the core. |
43
+ | `status` | Running state, ports, mode, toggles, uptime, traffic. |
44
+ | `mode [rule\|global\|direct]` | Get or set the routing mode. |
45
+ | `proxies [GROUP]` | List groups, members, current selection, last delay. |
46
+ | `select GROUP NODE` | Pick a node in a group. |
47
+ | `test [GROUP\|NODE] [--url U] [--timeout MS]` | Latency-test a group, a node, or every node. |
48
+ | `tun on\|off\|status` | Toggle TUN (transparent system-wide capture). |
49
+ | `system-proxy on\|off\|status` | Set/clear the OS HTTP/SOCKS proxy. |
50
+ | `lan on\|off\|status` | Toggle `allow-lan` (let other devices use this box). |
51
+ | `logs [-f] [-n N] [--level L]` | Tail the log file, or stream live via the API. |
52
+ | `conns [--close]` | Show (or close) active connections. |
53
+ | `dashboard` | Print a web dashboard URL wired to the running core. |
54
+ | `enable` / `disable` | Autostart at login via a systemd `--user` unit. |
55
+ | `install [--upgrade]` | Pre-download the mihomo binary. |
56
+
57
+ ## Subscriptions & profiles
58
+
59
+ ```bash
60
+ usm clash sub add https://provider.example/sub?token=… --name work
61
+ usm clash sub add ./my-clash.yaml --name local # a local Clash config file
62
+ usm clash sub ls
63
+ usm clash sub update work # re-fetch
64
+ usm clash use work # switch active profile
65
+ ```
66
+
67
+ Subscriptions are fetched with a Clash User-Agent, so providers return a
68
+ **Clash-format YAML** (this is what carries the node list, groups, and rules —
69
+ mihomo understands every node protocol inside it: ss, vmess, vless, trojan,
70
+ hysteria2, tuic, …). The `Subscription-Userinfo` header (traffic used / total,
71
+ expiry) is parsed and shown in `sub ls`.
72
+
73
+ !!! note "Use the Clash subscription link"
74
+ Point `sub add` at the provider's **Clash / Clash.Meta** subscription URL.
75
+ Raw base64 node-list links (the generic "v2ray" format) are not supported —
76
+ ask your provider for the Clash link (almost all offer one).
77
+
78
+ Remote profiles auto-refresh on `up`/`restart` once older than `--interval`
79
+ hours (default 12; `0` disables).
80
+
81
+ ## Running & status
82
+
83
+ ```bash
84
+ usm clash up # start with the active profile
85
+ usm clash up work --lan # switch profile + allow LAN in one go
86
+ usm clash status
87
+ usm clash down
88
+ ```
89
+
90
+ `status` shows the running state, mixed port, controller, mode, and the
91
+ TUN / LAN / system-proxy toggles, plus live traffic totals when running:
92
+
93
+ ```
94
+ status ● running (pid 12345)
95
+ profile work
96
+ mode rule
97
+ mixed port 127.0.0.1:7890
98
+ controller 127.0.0.1:9090
99
+ tun off
100
+ allow-lan on
101
+ system-proxy off
102
+ autostart off
103
+ uptime 3m12s
104
+ traffic: ↓ 1.2GiB ↑ 88.4MiB | active conns: 7
105
+ ```
106
+
107
+ Your apps connect to the **mixed port** (`127.0.0.1:7890` by default), which
108
+ speaks **HTTP and SOCKS5 on the same port**.
109
+
110
+ ## Mode, node selection, latency tests
111
+
112
+ ```bash
113
+ usm clash mode global # rule | global | direct (instant via API)
114
+ usm clash proxies # all groups, members, current pick, last delay
115
+ usm clash proxies PROXY # just one group
116
+ usm clash select PROXY hk-01 # choose a node
117
+ usm clash test PROXY # latency-test every node in the group
118
+ usm clash test hk-01 # test a single node
119
+ usm clash test # test all nodes
120
+ ```
121
+
122
+ Node selections persist across restarts (`profile.store-selected`).
123
+
124
+ ## TUN — transparent, system-wide
125
+
126
+ TUN captures **all** OS traffic (not just apps that honor proxy settings) by
127
+ creating a virtual network interface. It needs `CAP_NET_ADMIN`:
128
+
129
+ ```bash
130
+ sudo setcap cap_net_admin,cap_net_bind_service+ep ~/.cache/usm/bin/mihomo
131
+ usm clash tun on # then this works without per-run sudo
132
+ usm clash tun off
133
+ ```
134
+
135
+ `usm clash tun on` prints the exact `setcap` line if the capability is missing.
136
+ When TUN is on, a sane DNS block (fake-ip) is injected if your profile doesn't
137
+ already define one.
138
+
139
+ ## System proxy & LAN
140
+
141
+ ```bash
142
+ usm clash system-proxy on # set the OS HTTP/HTTPS/SOCKS proxy to the core
143
+ usm clash system-proxy off # restore the previous setting
144
+ usm clash lan on # bind 0.0.0.0 so other LAN devices can use it
145
+ ```
146
+
147
+ `system-proxy` integrates with GNOME (`gsettings`), macOS (`networksetup`), and
148
+ Windows (registry). On any system it also writes shell exports to
149
+ `~/.cache/usm/clash/proxy.env` for terminal apps:
150
+
151
+ ```bash
152
+ source ~/.cache/usm/clash/proxy.env # http_proxy/https_proxy/all_proxy
153
+ ```
154
+
155
+ ## Logs, connections, dashboard
156
+
157
+ ```bash
158
+ usm clash logs -n 100 # tail the log file
159
+ usm clash logs -f # stream live logs via the API (Ctrl-C to stop)
160
+ usm clash conns # active connections (host, chain, rule, up/down)
161
+ usm clash conns --close # drop all connections
162
+ usm clash dashboard # prints a metacubexd URL wired to your core
163
+ ```
164
+
165
+ The dashboard URL embeds your controller host/port/secret; mihomo serves the
166
+ API with CORS enabled, so the hosted UI connects straight to your local core.
167
+
168
+ ## State & files
169
+
170
+ Everything lives under `~/.cache/usm/clash/`:
171
+
172
+ - `profiles/<name>.yaml` + `<name>.json` — the config and its metadata.
173
+ - `state.json` — active profile, port, mode, toggles, controller secret, pid.
174
+ - `runtime.yaml` — the composed config actually fed to mihomo (regenerated on
175
+ every start from the active profile + your overrides).
176
+ - `mihomo.log`, `cache.db` (node-selection persistence), `proxy.env`.
177
+
178
+ `runtime.yaml` always overrides `mixed-port`, `external-controller`, `secret`,
179
+ `mode`, `allow-lan`, and `tun` so the manager stays in control regardless of
180
+ what the subscription set.
181
+
182
+ ## Autostart at boot (systemd)
183
+
184
+ ```bash
185
+ usm clash enable # ~/.config/systemd/user/usm-clash.service + start now
186
+ usm clash disable
187
+ ```
188
+
189
+ The unit runs `usm clash run` in the foreground, restarts on failure, and
190
+ starts after `network-online.target`. As with [`usm tunnel`](tunnel.md), user
191
+ units only start at boot once linger is on:
192
+
193
+ ```bash
194
+ sudo loginctl enable-linger "$USER"
195
+ ```
196
+
197
+ (System-proxy is a desktop-session setting and is not managed by the systemd
198
+ unit; toggle it interactively with `usm clash system-proxy on`.)
199
+
200
+ ## `usm clash` vs `usm proxy`
201
+
202
+ | | `usm clash` | [`usm proxy`](proxy.md) |
203
+ | --- | --- | --- |
204
+ | Role | Full **client manager** (ClashX-style) | Lightweight **server** + simple **client** |
205
+ | Config source | Subscriptions / Clash profiles | A single upstream URL + a few rules |
206
+ | Runtime control | mode, node selection, delay tests, live logs (API) | none (static) |
207
+ | TUN / system-proxy / LAN | yes | no |
208
+ | Best for | Daily driver with many nodes & rules | Turning a box into a proxy, or a quick one-off client |
@@ -14,6 +14,8 @@ Every subcommand of `usm` falls into one of two buckets:
14
14
  | Command | Page |
15
15
  | --- | --- |
16
16
  | `tunnel` | [SSH tunnel manager](tunnel.md) |
17
+ | `proxy` | [HTTP/SOCKS/Clash proxy (mihomo)](proxy.md) |
18
+ | `clash` | [ClashX-style mihomo manager](clash.md) |
17
19
  | `gpu` | [GPU picker/watch](gpu.md) |
18
20
  | `port` | [Port discovery/kill](port.md) |
19
21
  | `notify` | [Long-task pings](notify.md) |
@@ -0,0 +1,213 @@
1
+ # `usm proxy`
2
+
3
+ Turn a machine into a proxy other hosts dial into, **and/or** run a local
4
+ [Clash](https://github.com/MetaCubeX/mihomo) client that sends only
5
+ rule-matched traffic out through it. Both roles are driven by a single
6
+ auto-installed [mihomo](https://github.com/MetaCubeX/mihomo) (Clash.Meta)
7
+ binary, with the same persistent state, short ids, and optional systemd
8
+ autostart you get from [`usm tunnel`](tunnel.md).
9
+
10
+ ## Two roles
11
+
12
+ | Role | What it does |
13
+ | --- | --- |
14
+ | `server` | Make **this** box a proxy: a mixed HTTP+SOCKS inbound (optionally password-protected) and/or an encrypted `ss://` (Shadowsocks) inbound. It forwards everything straight out (`mode: direct`). |
15
+ | `client` | Run a local mixed HTTP+SOCKS inbound for your apps; traffic that matches a rule goes out through a remote proxy, everything else stays direct. |
16
+
17
+ ```
18
+ your apps ──▶ usm proxy client (127.0.0.1:7890)
19
+ │ rule match → PROXY
20
+ ▼
21
+ usm proxy server (host:7890 / ss://host:8388)
22
+ │
23
+ ▼
24
+ the internet
25
+ ```
26
+
27
+ ## Subcommands
28
+
29
+ | Command | What it does |
30
+ | --- | --- |
31
+ | `server [OPTIONS]` | Define + start a proxy server on this box. |
32
+ | `client UPSTREAM [OPTIONS]` | Define + start a client that routes through `UPSTREAM`. |
33
+ | `url <id>` | Print the connect URLs (`http://`, `socks5://`, `ss://`) for a server. |
34
+ | `ls [--prune]` | List proxies with role / route / PID / uptime / status / boot flag. |
35
+ | `start <id>` | Relaunch a stopped proxy (or `systemctl start` if enabled). |
36
+ | `stop <id\|all>` | Stop a proxy but **keep the definition** for later. |
37
+ | `restart <id>` | `stop` + `start` (or `systemctl restart` if enabled). |
38
+ | `rm <id\|all>` | Delete the definition (also disables systemd if enabled). |
39
+ | `enable <id>` | Install a `systemd --user` unit and start it. |
40
+ | `disable <id>` | Remove the unit (keeps the definition). |
41
+ | `show <id>` | Dump the definition as JSON (passwords redacted). |
42
+ | `logs <id> [-n N]` | Print the tail of the per-proxy log. |
43
+ | `install [--upgrade]` | Pre-download the mihomo binary. |
44
+
45
+ ## Server
46
+
47
+ ```bash
48
+ usm proxy server # mixed HTTP+SOCKS on 0.0.0.0:7890
49
+ usm proxy server --auth alice:s3cret # require username/password
50
+ usm proxy server --ss # also expose an encrypted ss:// inbound
51
+ usm proxy server --ss --no-mixed --host 1.2.3.4 # ss:// only, advertise a public IP
52
+ ```
53
+
54
+ | Flag | Default | Meaning |
55
+ | --- | --- | --- |
56
+ | `-p`, `--port N` | `7890` | Mixed HTTP+SOCKS inbound port. |
57
+ | `--mixed / --no-mixed` | `--mixed` | Expose the mixed HTTP+SOCKS inbound. |
58
+ | `--listen ADDR` | `0.0.0.0` | Bind address for the inbounds. |
59
+ | `--auth USER:PASS` | — | Require credentials on the HTTP/SOCKS inbound. |
60
+ | `--ss` | off | Also expose an encrypted Shadowsocks inbound. |
61
+ | `--ss-port N` | `8388` | Shadowsocks port (implies `--ss`). |
62
+ | `--cipher NAME` | `aes-256-gcm` | Shadowsocks cipher. |
63
+ | `--password PW` | random | Shadowsocks password (a random one is generated if omitted). |
64
+ | `--host H` | auto | Host/IP advertised by `url` (set this to your public IP). |
65
+ | `--name NAME` | next integer | Custom id. |
66
+
67
+ After starting, `usm proxy url <id>` prints ready-to-paste connect strings:
68
+
69
+ ```bash
70
+ $ usm proxy url 0
71
+ http://alice:s3cret@1.2.3.4:7890
72
+ socks5://alice:s3cret@1.2.3.4:7890
73
+ ss://YWVzLTI1Ni1nY206…@1.2.3.4:8388#usm-0
74
+ ```
75
+
76
+ !!! warning "Plain HTTP/SOCKS is unencrypted"
77
+ The mixed inbound carries traffic in the clear. Expose it only on a
78
+ trusted network, behind `--auth`, or tunneled (e.g. via
79
+ [`usm tunnel`](tunnel.md)). For the public internet, use the `ss://`
80
+ inbound (`--ss`), which is encrypted, and open the port in your firewall.
81
+
82
+ ## Client
83
+
84
+ Feed `client` any proxy URL — including a line straight out of
85
+ `usm proxy url`:
86
+
87
+ ```bash
88
+ usm proxy client http://alice:s3cret@1.2.3.4:7890 # via HTTP
89
+ usm proxy client socks5://1.2.3.4:1080 # via SOCKS5
90
+ usm proxy client 'ss://YWVz…@1.2.3.4:8388' # via Shadowsocks
91
+ ```
92
+
93
+ Then point your apps at `http://127.0.0.1:7890` (HTTP **and** SOCKS on the
94
+ same port):
95
+
96
+ ```bash
97
+ export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890
98
+ curl https://ifconfig.me # comes out of the server
99
+ ```
100
+
101
+ | Flag | Default | Meaning |
102
+ | --- | --- | --- |
103
+ | `-p`, `--port N` | `7890` | Local mixed HTTP+SOCKS inbound for your apps. |
104
+ | `--listen ADDR` | `127.0.0.1` | Bind address for the local inbound. |
105
+ | `--rule RULE` | — | Extra mihomo rule (repeatable), e.g. `'DOMAIN-SUFFIX,github.com,PROXY'`. |
106
+ | `--rules-file F` | — | Read rules from a file (one per line; `#` comments ignored). |
107
+ | `--final proxy\|direct` | `proxy` | Where **unmatched** traffic goes (the trailing `MATCH` rule). |
108
+ | `--controller [ADDR]` | off | Enable mihomo's RESTful API (default `127.0.0.1:9090`). |
109
+ | `--secret S` | — | Secret for the external controller. |
110
+ | `--name NAME` | next integer | Custom id. |
111
+
112
+ ### How rules are assembled
113
+
114
+ The generated `rules:` block, top to bottom, is:
115
+
116
+ 1. Private / loopback ranges (`127.0.0.0/8`, `10.0.0.0/8`, `192.168.0.0/16`,
117
+ `::1`, …) → `DIRECT`, so LAN and localhost never loop through the proxy.
118
+ 2. Your `--rule` / `--rules-file` lines, verbatim, in order.
119
+ 3. `MATCH,<final>` — the catch-all (`PROXY` by default, `DIRECT` with
120
+ `--final direct`).
121
+
122
+ Two common shapes fall out of this:
123
+
124
+ === "Everything through the server (default)"
125
+
126
+ ```bash
127
+ usm proxy client http://alice:s3cret@1.2.3.4:7890
128
+ # private ranges stay direct; everything else → the server
129
+ ```
130
+
131
+ === "Only specific traffic through the server"
132
+
133
+ ```bash
134
+ usm proxy client http://1.2.3.4:7890 \
135
+ --rule 'DOMAIN-SUFFIX,github.com,PROXY' \
136
+ --rule 'DOMAIN-SUFFIX,openai.com,PROXY' \
137
+ --final direct
138
+ # only github.com / openai.com go through the server; the rest is direct
139
+ ```
140
+
141
+ Rules use mihomo's syntax — `DOMAIN-SUFFIX`, `DOMAIN-KEYWORD`, `IP-CIDR`,
142
+ `GEOIP`, `PROCESS-NAME`, etc. See the
143
+ [mihomo rules docs](https://wiki.metacubex.one/config/rules/). The config is
144
+ validated with `mihomo -t` before launch, so a typo fails fast with the exact
145
+ parser error.
146
+
147
+ ## End-to-end example
148
+
149
+ On the server (a well-connected box):
150
+
151
+ ```bash
152
+ usm proxy server --ss --auth alice:s3cret --host 203.0.113.10
153
+ usm proxy url 0 # copy the ss:// line
154
+ usm proxy enable 0 # optional: autostart at boot
155
+ ```
156
+
157
+ On your laptop:
158
+
159
+ ```bash
160
+ usm proxy client 'ss://YWVz…@203.0.113.10:8388'
161
+ export https_proxy=http://127.0.0.1:7890
162
+ ```
163
+
164
+ ## Ids, state, and logs
165
+
166
+ `server` / `client` assign the next free non-negative integer as the id
167
+ (`0`, `1`, …); pass `--name foo` for a memorable one. Each proxy lives under
168
+ `~/.cache/usm/proxy/<id>/`:
169
+
170
+ - `state.json` — the definition (`stop` keeps it; `rm` deletes it).
171
+ - `config.yaml` — the mihomo config, regenerated from `state.json` on every start.
172
+ - `mihomo.log` — appended on each (re)start; read it with `usm proxy logs <id>`.
173
+
174
+ ```bash
175
+ usm proxy ls
176
+ usm proxy show 0 # passwords shown as ***
177
+ usm proxy logs 0 -n 100
178
+ usm proxy rm all
179
+ ```
180
+
181
+ ## The mihomo binary
182
+
183
+ The first run downloads a pinned mihomo release into
184
+ `~/.cache/usm/bin/mihomo` (`chmod +x`) — no system packages, no sudo, same
185
+ mechanism as [`usm serve`](serve.md). Pre-fetch it with `usm proxy install`,
186
+ refresh with `usm proxy install --upgrade`, or point `$USM_MIHOMO_BIN` at your
187
+ own build to bypass the download entirely.
188
+
189
+ ## Autostart at boot (systemd)
190
+
191
+ `usm proxy enable <id>` writes
192
+ `~/.config/systemd/user/usm-proxy-<id>.service`, runs `daemon-reload`, then
193
+ `systemctl --user enable --now`. The unit runs `usm proxy up <id>` in the
194
+ foreground, restarts on failure, and starts after `network-online.target` —
195
+ exactly like [`usm tunnel`](tunnel.md#autostart-at-boot-systemd).
196
+
197
+ !!! warning "Linger for actual boot-time start"
198
+ User units only start at login unless linger is on:
199
+
200
+ ```bash
201
+ sudo loginctl enable-linger "$USER"
202
+ ```
203
+
204
+ `usm proxy enable` prints this hint when linger isn't set yet.
205
+
206
+ ## How is this different from `usm tunnel socks`?
207
+
208
+ [`usm tunnel socks`](tunnel.md) gives you a SOCKS5 proxy over an **SSH**
209
+ connection — great when you already have SSH access and want all traffic to
210
+ exit through that host. `usm proxy` instead runs a **standalone proxy daemon**:
211
+ it supports HTTP and SOCKS together, an encrypted `ss://` transport for the
212
+ public internet, and — on the client side — Clash **rules** so only the
213
+ traffic you choose is routed through the server.
@@ -48,6 +48,8 @@ you want from the [Commands](commands/index.md) section.
48
48
  | Command | What it does |
49
49
  | --- | --- |
50
50
  | [`usm tunnel`](commands/tunnel.md) | SSH tunnels (local / remote / SOCKS) with state + systemd autostart |
51
+ | [`usm proxy`](commands/proxy.md) | Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy, or a Clash client routing rule-matched traffic through one (mihomo) |
52
+ | [`usm clash`](commands/clash.md) | ClashX-style CLI manager for mihomo: subscriptions, TUN, mode, node selection, system proxy, LAN, live logs, latency tests |
51
53
  | [`usm gpu`](commands/gpu.md) | GPU inventory, free-picker, watch, kill (nvidia-smi wrapper) |
52
54
  | [`usm port`](commands/port.md) | Show what's on a port; kill the holder |
53
55
  | [`usm notify`](commands/notify.md) | Wrap a command and ping ntfy.sh / Telegram / webhook when it exits |
@@ -67,6 +67,8 @@ nav:
67
67
  - Commands:
68
68
  - Overview: commands/index.md
69
69
  - tunnel — SSH tunnels: commands/tunnel.md
70
+ - proxy — HTTP/SOCKS/Clash proxy: commands/proxy.md
71
+ - clash — ClashX-style manager: commands/clash.md
70
72
  - gpu — GPU picker/watch: commands/gpu.md
71
73
  - port — Port discovery/kill: commands/port.md
72
74
  - notify — Long-task pings: commands/notify.md
@@ -173,8 +173,31 @@
173
173
  "click>=8.2.1",
174
174
  "rich>=13.0"
175
175
  ],
176
- "version": "1.0.4",
177
- "hash": "sha256:81f3c620cdc2eeb2541b2871e207c63fca9e551db550224fda5c1dbb16d4ae11"
176
+ "version": "1.0.5",
177
+ "hash": "sha256:70321a5c70f82028df09fe8cdab2ab8b6da9e00dfcc968ee688beebd80e47e52"
178
+ },
179
+ "proxy": {
180
+ "description": "Turn a box into an HTTP/SOCKS (+Shadowsocks) proxy, or a Clash client routing rule-matched traffic through one (mihomo).",
181
+ "path": "proxy.py",
182
+ "requirements": [
183
+ "click>=8.2.1",
184
+ "pyyaml>=6.0.3",
185
+ "rich>=13.0"
186
+ ],
187
+ "version": "1.0.1",
188
+ "hash": "sha256:c25c6135837d711225a4fa60159e4d44b7f3724f362fe57da8893a0c4db1bd14"
189
+ },
190
+ "clash": {
191
+ "description": "ClashX-style CLI manager for the mihomo core: subscriptions, TUN, rule/global/direct mode, node selection, system proxy, LAN, live logs, latency tests.",
192
+ "path": "clash.py",
193
+ "requirements": [
194
+ "click>=8.2.1",
195
+ "pyyaml>=6.0.3",
196
+ "requests>=2.32.4",
197
+ "rich>=13.0"
198
+ ],
199
+ "version": "1.0.2",
200
+ "hash": "sha256:a8871d90263a5c6454e35c91c224ad26dcf0860255b529606b5a4a453bffebe6"
178
201
  }
179
202
  }
180
203
  }