Persistent SSH reverse tunnel daemon CLI. Auto-reconnect with exponential backoff + jitter.
Repo slow-stack/ponte, read from GitHub 2 d ago. slow-stack has not joined Take My Repo.
slow-stack/ponte is a public repo on GitHub by slow-stack. Persistent SSH reverse tunnel daemon CLI. Auto-reconnect with exponential backoff + jitter. It declares the Apache-2.0 license on GitHub. It is written mainly in Python, has 1 stars and last changed on 2026-10-02. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-20.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
A persistent SSH tunnel daemon — reverse, local & SOCKS · 持久 SSH 隧道守护工具(反向 / 本地 / SOCKS)
Keep
ssh -Nforwardings alive across network drops and reboots — reconnect with exponential backoff + jitter, and register an OS-level auto-start service so it survives crashes.
[[tunnels]] rules are tagged by
kind: remote (-R, the default), local (-L) and dynamic (-D, a
SOCKS5 proxy). Mix them freely — they share one SSH connection. Duplicate listen
ports are rejected at config load, before ExitOnForwardFailure can turn a
typo into an endless reconnect loop.[[profiles]] gives each SSH endpoint a
name, its own key and its own forwarding rules. Every profile is supervised
independently (own connection, reconnect budget, health checks and status
file section), so one unreachable server no longer drags the others down,
and ponte status / ponte watch have a row per tunnel. A pre-profiles
config is read as a single profile named default.max_retries=0 = retry forever), so a drop never becomes a dead
tunnel. A session that stays up ≥ stable_after seconds resets the retry
budget, so a long-running tunnel is never abandoned after a few flaky drops.ponte reload re-reads the config and restarts only the
profiles whose settings actually changed, so adding a tunnel (or fixing one
server) no longer drops every other connection. kill -HUP does the same on
POSIX. A config with a typo in it is rejected before the daemon sees it and the
running tunnels are left untouched.~/.ssh/config still counts — only host is required in [ssh].
Leave out user and/or identity_file and ponte stops forcing user@ and
-i, so OpenSSH resolves them itself: Host aliases, User, IdentityFile,
ssh-agent. A machine where ssh myserver already works needs no duplication,
and ponte no longer overrides an IdentityFile you set there.
ponte config --ssh-command prints the exact command line it will run.jump = "ops@bastion" in [ssh] reaches a
server only the bastion can see. It is handed to ssh -J verbatim (comma
separated for a chain, [user@]host[:port] per hop), so OpenSSH builds the
hop itself and the bastion's user/key come from ~/.ssh/config as well — no
second key path to keep in sync. ponte doctor probes the one hop that is
actually reachable from here and says "the bastion is unreachable" instead of
leaving you with a login failure, while ponte test validates the whole chain.install registers an OS auto-start service:
boot-or-logon Scheduled Task (Windows), systemd user unit (Linux), launchd agent (macOS).MaxStartups
is never hammered.[notify].on_consecutive_failures
failed attempts in a row, ponte pushes to an ntfy topic and/or a JSON webhook,
at most once per cooldown for the same tunnel, and re-arms only after a
session that stays up ≥ stable_after seconds. ponte notify-test proves the
channel works before the outage. Off by default: nothing leaves your machine
unless you enable it.ponte doctor — one command that checks the config, the key file and
its permissions, SSH reachability, listening ports, auto-start status and the
notify channel, each row ending in a concrete fix instead of a black box.ponte serve puts the same status
on HTTP: / is a self-contained dashboard (one file, no CDN, no external
assets, complete without JavaScript), /healthz
answers 503 when a tunnel is actually broken, /metrics speaks Prometheus
and /status.json is exactly ponte status --json. Loopback-only by default;
exposing it needs an explicit token.ssh automatically, per-platform runtime
paths, and portable remote-port probing (socket → ss/lsof/netstat).pipx install ponte-cli # or: pip install ponte-cli (pipx keeps it isolated)
ponte init # create the config file and print its path
$EDITOR ~/.config/ponte/config.toml # set host/user, point identity_file at your key
ponte test # verify SSH connectivity
ponte start # run the daemon in the background
ponte status # check process + remote ports
ponte install # register auto-start + crash restart
No config file yet? ponte init writes one from the shipped template. The
config lives outside the package, so pip install -U ponte-cli never
touches it. The PyPI distribution is ponte-cli, while the command and the
import package stay ponte; a checkout installs the same way (pipx install .).
| Command | Purpose |
|---|---|
init [--path P] [--force] |
write a config file from the template (never overwrites without --force) |
start / start --foreground |
start daemon in background / foreground (debug) |
stop / restart |
graceful stop / stop-then-start |
reload |
re-read the config and restart only the tunnels whose settings changed |
status [--json] |
per-profile health, ports and tunnel statistics (--json for scripts) |
watch [--interval S] |
live dashboard: per-profile health, session uptime, reconnects, event feed |
logs [-n N] [--follow] |
view / tail the daemon log |
test [--profile NAME] |
quick SSH connectivity check (every profile by default) |
check [--profile NAME] |
verify tunnel ports are listening (-R on the server, -L/-D locally) |
doctor [--offline] [--timeout S] [--json] |
one-shot checkup of config, key, connectivity, ports, auto-start and notifications, each row with a fix (--json for scripts) |
notify-test [--profile NAME] |
send a test alert through the configured ntfy / webhook channels |
serve [--host H] [--port P] [--token T] [--open] [--demo] |
local HTTP dashboard, /healthz probe, Prometheus /metrics, /status.json snapshot; --demo serves built-in sample data |
install / uninstall |
register / remove the OS auto-start service |
config [--ssh-command] |
print the effective configuration, its source file and any warnings (--ssh-command prints the exact ssh argv) |
Global options (before the command): --config/-c PATH pin a config file,
--version/-V print the version. Unknown/typo'd config keys are reported by
ponte config instead of being silently ignored. Run
ponte --install-completion once to add shell completion
(bash / zsh / fish / PowerShell).
ponte watch is for the machine you are sitting at; ponte serve is for
everything else — a browser, a phone on the same host, Uptime Kuma, Prometheus.
ponte serve # http://127.0.0.1:8787/ (loopback only by default)
ponte serve --open # ...and open it in your browser
No tunnels yet? ponte serve --demo runs the same server on built-in sample
data: a small timeline that connects, drops, backs off and reconnects on its own,
so the page shows every state it has — healthy, broken, and unknown (a probe
that could not answer). A 演示时钟 line in the footer says which moment you are
looking at, and 冻结 / −10s / +10s / 下一处变化 / 回到现在 next to it
drive the timeline: 下一处变化 jumps to the next change that is visible on the
board, so a fault state is one click away instead of 140 seconds of healthy
staring (two adjacent phases that look identical are skipped — a button landing
where nothing changed reads as broken). Those buttons only move a number in the
URL (?at=<seconds>): the server holds no state, a live ponte serve ignores the
parameter, and a copied link shows that exact moment to whoever opens it. It reads
no config and never touches a daemon, and the payload
("demo": {"at": …, "anchored": …, "next_at": …}), the page header and the CLI
output all say the data is a demo: a dashboard screenshot names your servers, so
it must not be mistakable for somebody's real infrastructure. Sample hosts use
example.com.
| Endpoint | What it answers |
|---|---|
/ |
the dashboard: one row per tunnel — verdict, destination and jump chain, forwarded ports as chips, session age, availability, last disconnect reason; click a row for the full statistics and the event feed. Light and dark, refreshed in place (expanded rows and scroll position survive), and a <noscript> reload if scripting is off |
/healthz |
200 while the tunnels work, 503 as soon as one is broken — the endpoint to point a monitor at |
/metrics |
Prometheus text exposition: session age, cumulative up/down time, availability, reconnects, port-listening state |
/status.json |
exactly the payload of ponte status --json |
Why /healthz and /metrics disagree on purpose. /healthz fails, so a
monitor can alert; /metrics always answers 200 and reports state as numbers,
because a scrape failure would hide why a tunnel went down — which is exactly
what a graph exists to show. And /healthz reports starting (with 200) until
the first health check completes, so restarting the daemon does not page you.
"Unknown" is not "down". The remote probe is an SSH connection of its own,
and on a shared/NATed uplink it fails on its own often enough (roughly a third
of ticks in our measurements). So a check that could not be completed is kept
apart from a check that produced a verdict: /healthz answers 200 unverified
(not 503), ponte status shows 未知 with the probe's reason instead of
异常, the dashboard prints 未观测 for a port group the probe never reached
instead of a red 未监听, and ponte_profiles_unknown counts them. Only a conclusive failure — the SSH process gone, or a port a probe
did reach and found closed — pages you or triggers the zombie-session
reconnect.
Security. The dashboard names your servers, users and forwarded ports — it
is a map of your infrastructure, not a status line. So ponte serve binds
127.0.0.1 and nothing else. Binding a LAN or public address is possible, but
only together with a token; ponte refuses the combination of "exposed" and
"no token" instead of warning about it:
[serve]
host = "0.0.0.0" # opt in, deliberately
port = 8787
token = "a-long-random-string" # required for any non-loopback host
refresh = 5 # dashboard auto-refresh, seconds
# ipv6 hosts are fine too: host = "::1"
Loopback is decided by parsing the address, never by matching its spelling: a
name such as 127.corp.example resolves wherever its owner points it, so it
counts as exposed and needs a token. Shorthand the OS would accept but the
parser does not (127.1, or the absolute form localhost.) also counts as
exposed — the error message says so, and 127.0.0.1 is what the default uses
anyway.
Clients then pass ?token=... (handy for scrapers) or Authorization: Bearer .... All four endpoints are read-only, re-read the daemon status per request and
send Cache-Control: no-store, so a page can never show a stale "healthy" for a
tunnel that has since died.
# prometheus.yml
scrape_configs:
- job_name: ponte
static_configs:
- targets: ["127.0.0.1:8787"]
# with a token: metrics_path: /metrics?token=a-long-random-string
Alert on ponte_profile_port_listening == 0 for the signal that matters most:
a live process whose forwarded port is gone is the classic silent failure.
| Platform | Mechanism | Generated artifact |
|---|---|---|
| Windows | Scheduled Task (boot or logon) | Register-ScheduledTask (pythonw -m ponte.main --config <file> start --foreground) |
| Linux | systemd user unit | ~/.config/systemd/user/ponte.service |
| macOS | launchd LaunchAgent | ~/Library/LaunchAgents/com.modusensus.ponte.plist |
The daemon is always launched with an explicit --config, so a service running
under a different account (e.g. a SYSTEM Scheduled Task) still reads your
config instead of silently falling back to another one.
ponte (local daemon, Python)
main.py ──▶ daemon.py ──▶ retry.py ──▶ core.py ──▶ ssh -N (-R/-L/-D)
(typer (lifecycle (infinite (pure SSH
CLI) orchestration) backoff) subprocess)
│
▼
health.py ── periodic checks: process alive + remote ports
main.py — typer CLI entrydaemon.py — lifecycle orchestration, service install/uninstall, graceful stopretry.py — exponential backoff + jitter reconnect state machinecore.py — SSH argument building, subprocess management, port probinghealth.py — periodic liveness + remote-port checksnotify.py — ntfy / webhook alerts on repeated failuresdoctor.py — one-shot diagnostics used by ponte doctorserve.py — read-only HTTP surface (dashboard / health probe / metrics) over
the same payload ponte status --json emitsconfig.py — TOML load/validate (built-in tomllib on 3.11+)Run ponte init, then edit the file it prints. All paths support ~ and
environment-variable expansion. Resolution order (first existing file wins):
--config PATH$PONTE_CONFIG%APPDATA%\ponte\config.toml (Windows),
~/.config/ponte/config.toml (Linux),
~/Library/Application Support/ponte/config.toml (macOS)ponte/config.toml inside the installed package — legacy, honoured only
so pre-0.3 installs keep working; it is overwritten by pip install -U, so
migrate with ponte init.Sections:
[ssh] — host / port / user / identity_file / known_hosts_file /
jump / options (any extra key there is passed through verbatim as
-o key=value).
Only host is required: leave out user and/or identity_file and ponte
stops forcing user@ and -i, so OpenSSH resolves them from your
~/.ssh/config (Host alias, User, IdentityFile) or ssh-agent.
ponte config --ssh-command shows the resulting command line.[ssh] jump — the bastion in front of host, in OpenSSH ProxyJump syntax:
"bastion", "ops@bastion", "ops@bastion:2222", or a chain such as
"ops@hop1, root@hop2". ponte passes it to ssh -J and never talks to the
hop itself, so the bastion's identity comes from its own Host block in
~/.ssh/config — there is deliberately no per-hop identity_file here.
proxy_jump is accepted as an alias (set only one). Combining jump with a
ProxyJump/ProxyCommand in [ssh.options] is rejected: those describe the
same hop and ssh would silently apply only one.[[profiles]] — an alternative to the single-tunnel layout: each entry has
name, its own [profiles.ssh] and its own [[profiles.tunnels]]. Mixed
with a top-level [ssh]/[[tunnels]] it is rejected rather than guessed at;
retry/health/daemon/service stay global policy for every profile.[[tunnels]] — forwarding rules. kind picks the flag and what the fields
mean: remote (default, -R: the server listens on remote_port and
forwards back to local_host:local_port), local (-L: this machine
listens on local_host:local_port and forwards to remote_host:remote_port)
and dynamic (-D: a SOCKS5 proxy on local_host:local_port). For -L/-D
the bind address defaults to 127.0.0.1, so an omitted field is never a LAN
exposure.[daemon] — pid/log paths (default per-platform: %LOCALAPPDATA%\ponte,
~/.local/state/ponte, ~/Library/Application Support/ponte), log rotation[retry] — max_retries (0 = forever), backoff params, jitter,
stable_after[health] — check interval, remote probe toggle/timeout,
max_check_interval (backoff ceiling while unhealthy)[notify] — enabled (default false), on_consecutive_failures,
cooldown (seconds between two alerts for the same profile), and the
channels: ntfy_topic (plus optional ntfy_server / ntfy_token) and/or
webhook_url, which receives the alert as JSON[service] — service name, autostart, POSIX kill grace[windows] — Windows-only knobs (task_name, ssh_exe, pythonw_exe,
run_as). run_as is user (default: logon-time, runs as you, can read
~/.ssh) or system (boot-time, survives login/reboot, needs elevation
and an identity file SYSTEM can read). pythonw_exe pins the windowless
interpreter the Scheduled Task runs: ponte refuses to install a task that
would fall back to python.exe, because that flashes a console window at
every logon.| Symptom | Where to look |
|---|---|
Permission denied (publickey) |
public key on server ~/.ssh/authorized_keys; on Windows strip inherited ACLs (icacls id_rsa /inheritance:r /grant:r <user>:(R)) |
| Connection rejected after key change | delete known_hosts, reconnect (StrictHostKeyChecking=accept-new default) |
| Server only reachable through a bastion | set [ssh] jump = "ops@bastion" — ponte hands it to ssh -J; ponte doctor then probes that hop and says whether the bastion itself is down |
| Process alive but remote port down | cloud security-group inbound rules; check server with ss -tlnp / lsof -nP -iTCP -sTCP:LISTEN — the daemon now force-reconnects a "zombie" tunnel after 3 consecutive failed checks |
| Console window flashes at logon, or while stopping | the Scheduled Task must run pythonw.exe — check [windows] pythonw_exe; ponte stop also force-kills through a hidden taskkill |
ponte serve exits with "cannot bind" / port busy |
another process holds the port — ponte serve --port 8788; the refused non-loopback bind is a token problem, and the message says so |
/healthz returns 401 |
a [serve].token is set: pass ?token=... or Authorization: Bearer ... |
/healthz returns 503 while the tunnel looks fine |
it reports the tunnel, not the process: read unhealthy / errors in the body, then ponte check |
/healthz returns 200 with "status": "unverified" |
the probe's own connection failed, so ponte cannot confirm the ports — read unknown, and check ponte logs if it persists |
| Logs | ponte logs -n 100 --follow |
pip install -e ".[dev]"
pytest --cov=ponte --cov-report=term-missing # threshold in pyproject.toml
ruff check . # lint
mypy # type check
python _smoke_test.py # zero-dependency quick check
CI runs lint + types on Linux, and the test suite across
Windows/Linux/macOS × Python 3.11–3.14, reporting coverage to
Codecov. One extra job re-runs the
suite with three injections — PONTE_TEST_THREAD_DELAY=0.15,
PONTE_TEST_THREAD_START_DELAY=0.15 and PONTE_TEST_THREAD_CPU=0.05: the first
stretches every worker-thread sleep and wait, the second holds a freshly started
thread before its first line runs (a case no amount of wait-stretching can
reach), and the third makes those same waits burn real CPU, so a test that
measures how much work fits in a budget is starved too. A test that only passes
on a fast machine fails there every time instead of flaking once in a while.
Set the same variables locally to reproduce such a machine. Another job runs the
suite under a C locale (non-UTF-8 stdio) in a half-hour timezone with
deprecation warnings as errors, and a build job installs the built wheel and
runs ponte init, so a packaging regression cannot ship again. See
CONTRIBUTING.md.
.gitignore excludes id_rsa /
id_rsa.pub; place your own keys on each machine.ponte.pid / ponte.status.json / ponte.stop /
ponte.log*) are generated and not committed.ponte init (it migrates the in-package file if one exists), then
ponte install again so the service picks up the new --config argument.tunnel.ps1, setup.ps1, ssh-tunnel.bat,
ssh-tunnel.vbs, fix-wsl-tunnel.sh) live in legacy/ and are
deprecated — the CLI replaces them. setup.ps1 copied your private key
into the project directory; do not use it.让
ssh -N -R在网络抖动与重启后依然存活——断线自动以指数退避 + 抖动重连, 并注册系统级开机自启服务,进程崩溃也能被拉活。
[[profiles]] 给每个 SSH 端点一个名字、
一套密钥和一组转发规则;每条 profile 各自重连、各自健康检查、在状态文件里
各占一段,所以一台服务器连不上不会拖垮其它隧道,ponte status / ponte watch
也是每条隧道一行。升级前的单隧道配置会被当作名为 default 的 profile 读取。[[tunnels]] 规则用 kind 区分:remote(-R,默认)、
local(-L)、dynamic(-D,SOCKS5 代理),可以混用且共用一条 SSH 连接。
重复的监听端口在加载配置时就会被拒绝,而不是让 ExitOnForwardFailure
把一次手误变成无限重连。max_retries=0 = 永远重试),
掉线不会变成死隧道。会话稳定运行 ≥ stable_after 秒后重试预算归零,
长跑隧道不会因前期几次抖动被永久放弃。ponte reload 重新读取配置,只重启真的改过的那几条
隧道:新增一条隧道、修好一台服务器,不再把其它正在跑的连接一起拆掉。
POSIX 下 kill -HUP 等价。配置写错时它会在守护进程看到之前就被拒绝,
正在跑的隧道不受影响。~/.ssh/config — [ssh] 里 host 是唯一必填项。
省略 user 和/或 identity_file 后,ponte 不再强行拼出 user@ 与 -i,
交给 OpenSSH 自己解析:Host 别名、User、IdentityFile、ssh-agent。
“ssh myserver 已经能用”的机器无需重复一份配置,ponte 也不会再覆盖你
写在 SSH 配置里的 IdentityFile。ponte config --ssh-command 打印最终命令。[ssh] 里写 jump = "ops@bastion" 就能连上只有堡垒机
看得到的服务器。它被原样交给 ssh -J(逐跳写 [user@]host[:port],多跳用
逗号分隔),跳板机这一段由 OpenSSH 自己建立,它的用户与密钥同样来自
~/.ssh/config,不需要再维护第二份密钥路径。ponte doctor 只探测本机真正
能直连的那一跳,直接告诉你“堡垒机连不上”,而不是丢一个登录失败给你;
ponte test 则验证整条链路。install 注册系统级开机自启服务:Windows 计划任务(开机或登录) /
Linux systemd user / macOS launchd。MaxStartups。[notify].on_consecutive_failures 次失败后,
向 ntfy 主题和/或 JSON webhook 推送一条告警;同一隧道每个 cooldown 秒最多
一条,且只有会话稳定运行 ≥ stable_after 秒才重新武装。ponte notify-test
让你在真出事之前就验证通道可用。默认关闭:不开启就绝不会外发任何数据。ponte doctor — 一条命令逐项体检:配置、密钥及其权限、SSH 连通性、
监听端口、开机自启状态、通知通道,每行都给出具体修法而不是留个黑箱。ponte serve 把同一份状态摆到 HTTP 上:/ 是一个
自包含的看板(单文件、不依赖 CDN 与任何外部资源,关掉脚本也能完整渲染),
/healthz 在隧道真的断时回 503,
/metrics 说 Prometheus 格式,/status.json 就是 ponte status --json。
默认只监听本机;要对外必须先给令牌。ssh、按平台落盘运行时文件、可移植的远程端口探测
(socket → ss/lsof/netstat)。pipx install ponte-cli # 或 pip install ponte-cli(pipx 会隔离安装)
ponte init # 生成配置文件并打印路径
$EDITOR ~/.config/ponte/config.toml # 填 host/user,identity_file 指向你的密钥
ponte test # 验证 SSH 连通性
ponte start # 后台启动守护进程
ponte status # 查看进程 + 远程端口
ponte install # 注册开机自启 + 崩溃重启
还没有配置文件?ponte init 会从内置模板生成一份。配置存放在包外,
pip install -U ponte-cli 不会覆盖它。PyPI 上的发行名是 ponte-cli,
命令与导入包名仍为 ponte(从源码目录安装同样可用 pipx install .)。
| 命令 | 用途 |
|---|---|
init [--path P] [--force] |
从模板生成配置文件(不加 --force 不覆盖) |
start / start --foreground |
后台启动 / 前台启动(调试) |
stop / restart |
优雅停止 / 停旧起新 |
reload |
重读配置,只重启设置真的变了的隧道 |
status [--json] |
逐条隧道的健康、端口与统计(--json 供脚本消费) |
watch [--interval S] |
实时看板:每条隧道一栏,含会话时长、重连次数与事件流 |
logs [-n N] [--follow] |
查看 / 跟读日志 |
test [--profile NAME] |
快速测 SSH 连通性(默认逐条测试) |
check [--profile NAME] |
检查隧道端口(-R 在服务器上,-L/-D 在本机) |
doctor [--offline] [--timeout S] [--json] |
一键体检配置、密钥、连通性、端口、自启与通知,每项给出修法(--json 供脚本消费) |
notify-test [--profile NAME] |
通过已配置的 ntfy / webhook 通道发一条测试通知 |
serve [--host H] [--port P] [--token T] [--open] [--demo] |
本地 HTTP 看板、/healthz 探活、Prometheus /metrics、/status.json 快照;--demo 用内置示例数据 |
install / uninstall |
注册 / 移除开机自启服务 |
config [--ssh-command] |
打印生效配置、来源文件与配置告警(--ssh-command 打印实际执行的 ssh 命令) |
全局选项(写在子命令之前):--config/-c PATH 指定配置文件,
--version/-V 打印版本。拼错/未知的配置项会由 ponte config 报出来,
不再被静默忽略。运行一次 ponte --install-completion 即可启用 shell 补全
(bash / zsh / fish / PowerShell)。
ponte watch 给坐在机器前的你看,ponte serve 给其它一切:浏览器、手机
(同机)、Uptime Kuma、Prometheus。
ponte serve # http://127.0.0.1:8787/(默认只监听本机)
ponte serve --open # 顺手在浏览器里打开
还没有隧道? ponte serve --demo 用内置的示例数据把同一个服务跑起来:一份自己会
连接、断线、退避、重连的小时间轴,于是页面上该有的状态都会出现——健康、异常,以及
未知(探针没能得出结论)。页脚有一行 演示时钟 告诉你现在看的是哪一刻,旁边的
冻结 / −10s / +10s / 下一处变化 / 回到现在 可以推着它走:下一处变化 跳到的是
看板上看得见的下一次变化,于是你不用干等那 140 秒的健康段就能看到故障态(相邻但外观
相同的两段会被跳过——落在一处什么都没变的地方,按钮看起来就是坏的)。这些按钮只是改
地址栏里的一个数字(?at=<秒>):服务端不持有任何状态、实时的 ponte serve 直接忽略
它、复制出去的链接谁打开都是同一刻。它不读配置、也不碰守护进程;payload
("demo": {"at": …, "anchored": …, "next_at": …})、页面头部与命令行输出三处都写明
这是演示数据:看板截图里写着服务器地址与端口,它不该被误读成某个人的真实基础设施。
示例主机名一律用 example.com。
| 接口 | 回答什么问题 |
|---|---|
/ |
看板:一行一条隧道——状态、目标与跳板机、端口 chips、会话时长、在线率、上次断线原因;点开该行看完整统计与事件流。跟随浅色/深色主题,原地刷新(展开的行与滚动位置都不会丢),关掉脚本则退化为整页刷新 |
/healthz |
隧道正常时 200,任一条断开立即 503 —— 监控就探这个 |
/metrics |
Prometheus 文本格式:会话时长、累计在线/离线、在线率、重连次数、端口监听状态 |
/status.json |
与 ponte status --json 完全一致的载荷 |
为什么 /healthz 与 /metrics 故意不一致。 /healthz 会失败,监控才能
报警;/metrics 永远回 200,把状态当数字报出来——因为采挂掉会盖住
“它为何挂了”,而那正是画图的目的。另外首次健康检查完成前,/healthz
报的是 starting(200),所以重启守护进程不会造成误报。
“未知”不是“挂了”。 远程端口探测本身就是一条独立的 SSH 连接,在共享/NAT
出口上它自己就会失败(我们实测约三分之一的检查如此)。所以 ponte 把“没问成”
和“问了、答案是坏的”分开:/healthz 回 200 unverified(而不是 503),
ponte status 显示黄色的 未知 并附上探测失败原因(而不是 异常),看板对探针
没探到的那一组端口写明「未观测」而不是画成红色的「未监听」,
ponte_profiles_unknown 单独计数。只有确凿的失败——SSH 进程没了,
或探针确实连上并看到端口没在听——才会报警或触发假死强制重连。
安全模型。 看板会列出你的服务器地址、登录用户与转发端口——这是一张
内网拓扑图,不是一行状态。所以 ponte serve 只绑 127.0.0.1。绑到局域网或
公网是可以的,但必须同时给令牌:ponte 对“对外 + 无令牌”的组合是直接
拒绝,而不是警告一句了事。
[serve]
host = "0.0.0.0" # 显式选择对外
port = 8787
token = "一个足够长的随机串" # 非回环地址必需
refresh = 5 # 看板自动刷新秒数
# 也支持 IPv6:host = "::1"
回环与否是解析地址得出的,不靠拼写匹配:像 127.corp.example 这样的名字
解析到哪里由它的所有者决定,所以它算“对外”,需要令牌。操作系统接受、但解析器
不认的简写(127.1,或绝对形式 localhost.)同样算“对外”——报错信息里会说明,
而默认值本来就是 127.0.0.1。
客户端用 ?token=...(脚本/采集器方便)或 Authorization: Bearer ...。
四个接口全是只读、每次请求都重新读取守护进程状态,并带
Cache-Control: no-store——所以页面不会拿旧的“健康”去骗一个已经挂了的隧道。
# prometheus.yml
scrape_configs:
- job_name: ponte
static_configs:
- targets: ["127.0.0.1:8787"]
# 带令牌时:metrics_path: /metrics?token=一个足够长的随机串
最值得拿来报警的一条是 ponte_profile_port_listening == 0:进程活着、
转发端口却没了,正是那种悄无声息的典型故障。
| 平台 | 机制 | 生成物 |
|---|---|---|
| Windows | 计划任务(开机或登录) | Register-ScheduledTask(pythonw -m ponte.main --config <文件> start --foreground) |
| Linux | systemd user 单元 | ~/.config/systemd/user/ponte.service |
| macOS | launchd LaunchAgent | ~/Library/LaunchAgents/com.modusensus.ponte.plist |
守护进程始终带显式 --config 启动:即使服务以其它身份运行(例如 SYSTEM
计划任务),读到的仍是你这份配置,而不是静默回退到别处。
ponte(本地守护进程,Python)
main.py ──▶ daemon.py ──▶ retry.py ──▶ core.py ──▶ ssh -N(-R/-L/-D)
(typer (生命周期 (无限退避 (纯 SSH
CLI) 编排) 重连) subprocess)
│
▼
health.py ── 周期检查:进程存活 + 远程端口(-R)+ 本地监听(-L/-D)
一个守护进程为每个 [[profiles]] 建一个 ProfileRunner(各自的 SSH 会话、
重连循环、健康检查),进程级的 pid / 状态文件 / 服务注册由守护进程统一持有;
状态文件按 profile 分区,所以一条隧道挂了不会影响其它隧道。
main.py — typer 命令行入口daemon.py — 生命周期编排、服务安装/卸载、优雅停止retry.py — 指数退避 + 抖动重连状态机core.py — SSH 参数构建、子进程管理、端口探测health.py — 周期存活 + 远程端口检查notify.py — 连续失败时的 ntfy / webhook 告警doctor.py — ponte doctor 使用的体检项serve.py — 只读 HTTP 接口(看板 / 探活 / 指标),渲染的就是
ponte status --json 那份载荷config.py — TOML 加载/校验(3.11+ 内置 tomllib)先运行 ponte init,再编辑它打印出的文件。所有路径支持 ~ 与环境变量展开。
查找顺序(先找到的生效):
--config PATH$PONTE_CONFIG%APPDATA%\ponte\config.toml、
Linux ~/.config/ponte/config.toml、
macOS ~/Library/Application Support/ponte/config.tomlponte/config.toml —— 旧位置,仅为兼容 0.3 之前的安装保留;
它会被 pip install -U 覆盖,请用 ponte init 迁移。各段含义:
[ssh] — host / port / user / identity_file / known_hosts_file /
jump / options(该表内未列出的键会原样透传为 -o key=value)。只有
host 必填:省略 user 和/或 identity_file 后,ponte 不再强行拼出
user@ 与 -i,由 OpenSSH 从 ~/.ssh/config(Host 别名、User、
IdentityFile)或 ssh-agent 解析。ponte config --ssh-command 可查看
最终命令行。[ssh] jump — 目标服务器前面的跳板机,写法就是 OpenSSH 的 ProxyJump:
"bastion"、"ops@bastion"、"ops@bastion:2222",或 "ops@hop1, root@hop2"
这样的多跳链路。ponte 把它交给 ssh -J,自己从不接触跳板机,所以跳板机的
身份来自它自己的 Host 块——这里刻意不提供第二份 identity_file。
proxy_jump 是等价的别名(只能写一个)。与 [ssh.options] 里的
ProxyJump/ProxyCommand 同时出现会被直接拒绝:它们说的是同一跳,
而 ssh 遇到重复设置只会静默采用其中一个。[[profiles]] — 单隧道写法的替代品:每个条目有 name、自己的
[profiles.ssh] 与 [[profiles.tunnels]]。与顶层 [ssh]/[[tunnels]]
混用会被拒绝(而不是猜你的意图);retry/health/daemon/service
仍是所有 profile 共用的全局策略。[[tunnels]] — 转发规则。kind 决定用哪个转发开关、各字段是什么意思:
remote(默认,-R)服务器监听 remote_port 并转发回
local_host:local_port;local(-L)本机监听 local_host:local_port
并转发到服务器侧的 remote_host:remote_port;dynamic(-D)在
local_host:local_port 上开一个 SOCKS5 代理。-L/-D 的绑定地址默认
127.0.0.1,省略字段不会意外暴露到局域网。[daemon] — pid/log 路径(平台默认:%LOCALAPPDATA%\ponte、
~/.local/state/ponte、~/Library/Application Support/ponte)、日志滚动[retry] — max_retries(0 = 无限)、退避参数、jitter、stable_after[health] — 检查间隔、远程探测开关/超时、max_check_interval
(不健康期间的间隔退避上限)[notify] — enabled(默认 false)、on_consecutive_failures、
cooldown(同一 profile 两条告警之间的最小秒数),以及通道:
ntfy_topic(可选 ntfy_server / ntfy_token)和/或 webhook_url
(以 JSON 形式收到告警)[serve] — 本地看板:host(默认 127.0.0.1)、port(默认 8787)、
token(绑定非回环地址时必填,否则拒绝启动)、refresh(看板刷新秒数)[service] — 服务名、自启、POSIX 强杀等待[windows] — 仅 Windows 使用(task_name、ssh_exe、pythonw_exe、
run_as)。run_as 默认 user(登录后以你本人身份运行、能读 ~/.ssh)或
system(开机即起、重启也能拉起,但需提权,且 identity_file
必须是 SYSTEM 能读到的文件)。pythonw_exe 指定计划任务使用的无窗口解释器:
若只能回退到 python.exe,ponte 会拒绝安装——那会导致每次登录弹出黑色窗口。| 症状 | 排查方向 |
|---|---|
| 「Permission denied (publickey)」 | 公钥是否加入服务器 ~/.ssh/authorized_keys;Windows 下私钥去掉继承 ACL(icacls id_rsa /inheritance:r /grant:r <用户名>:(R)) |
| 换 key 后连接被拒 | 删除 known_hosts 重连(默认 StrictHostKeyChecking=accept-new) |
| 服务器只能经堡垒机访问 | 配 [ssh] jump = "ops@bastion"——ponte 原样交给 ssh -J;之后 ponte doctor 会探测那一跳,直接说明堡垒机自身是否可达 |
| 进程活着但远程端口不通 | 云安全组入方向规则;服务器上 ss -tlnp / lsof -nP -iTCP -sTCP:LISTEN 确认监听 —— 守护进程已支持假死检测:连续 3 次检查失败自动强制重连 |
登录时(或 stop 时)闪出黑色控制台窗口 |
计划任务必须跑 pythonw.exe——检查 [windows] pythonw_exe;ponte stop 的强杀也已隐藏控制台 |
ponte serve 报绑定失败 / 端口占用 |
换端口:ponte serve --port 8788;若报的是非回环地址,那是令牌问题,报错里写了 |
/healthz 返回 401 |
配了 [serve].token:带上 ?token=... 或 Authorization: Bearer ... |
隧道看着正常,/healthz 却回 503 |
它报的是隧道不是进程:看响应体里的 unhealthy / errors,再用 ponte check 复核 |
/healthz 回 200 且 "status": "unverified" |
探测连接自己没建起来,ponte 无法确认端口状态:看 unknown 字段;持续如此就看 ponte logs |
| 排查日志 | ponte logs -n 100 --follow |
pip install -e ".[dev]"
pytest --cov=ponte --cov-report=term-missing # 阈值见 pyproject.toml
ruff check . # 静态检查
mypy # 类型检查
python _smoke_test.py # 零依赖快速自检
CI 在 Linux 上跑 lint + 类型检查,在 Windows/Linux/macOS × Python
3.11–3.14 上跑测试,覆盖率上报到
Codecov。另有一个任务会用三个注入再跑
一遍:PONTE_TEST_THREAD_DELAY=0.15、PONTE_TEST_THREAD_START_DELAY=0.15
与 PONTE_TEST_THREAD_CPU=0.05。第一条把工作线程的每次 sleep/wait 拉长;第二条让刚
start() 的线程迟迟跑不到第一行(没有任何等待可以被拉长的那种情况);第三条让这些
等待额外真的烧一段 CPU,于是"这段预算里该算完多少活"的断言也会被饿着。于是"只有机器够快
才通过"的测试会每次都在那里失败,而不是偶发地红一次。本地设同样三个变量即可
复现这种机器。
还有一个任务在 C locale(非 UTF-8 的 stdio)、半时区偏移下跑,并把弃用告警当错误;
build 任务会安装打好的 wheel 并执行 ponte init,避免打包问题再次溜进发布。详见
CONTRIBUTING.md。
.gitignore 已排除 id_rsa / id_rsa.pub;
各机器自行放置密钥。ponte.pid / ponte.status.json / ponte.stop /
ponte.log*)为生成物,不入库。ponte init
(若存在包内旧配置会直接迁移),然后重新 ponte install,
让服务带上新的 --config 参数。tunnel.ps1、setup.ps1、ssh-tunnel.bat、
ssh-tunnel.vbs、fix-wsl-tunnel.sh)已移到 legacy/ 并标记
为废弃,请改用 CLI。其中 setup.ps1 会把你的私钥复制进项目目录,
不要再使用。slow-stack/ponte is a public repo on GitHub by slow-stack. Persistent SSH reverse tunnel daemon CLI. Auto-reconnect with exponential backoff + jitter.
It declares the Apache-2.0 license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-10-02. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Reverse engineer anything with agents, from app behavior down to native binaries.

A collection of inspiring lists, manuals, cheatsheets, blogs, hacks, one-liners, cli/web tools and more.

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Various undocumented scripts for remote Raspberry Pi camera capture
The memory that dreams — long-term memory for AI agents. Readable files on your own machine, consolidated between sessions. Runs as a DeepSeek Harness plugin or over MCP.

DSH(DeepSeek Harness)学习工作台插件:Notion 式待办墙 + 按复习时长点亮的学习热力图 + 跨面板存活的番茄钟,零运行时依赖,只消费主题 token。
⚖️ The audit AI coding agents can't skip — deterministic facts (deleted-code provenance, symbol invocations, dependency pins) and six-gate claim adjudication for code security audits. Not another scanner.
信息源聚合 DSH 插件:定时摄取 RSS / B 站 / YouTube,读正文与字幕做本地预筛和三档判断,每轮出一份增量汇报。彻底不做平台互动。
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/slow-stack/ponteTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.