port-to-public

Port to Public

Temporarily expose the HTTP(S) service on this machine's localhost、127.0.0.1 or ::1 as a random https://*.trycloudflare.com address.

Security boundary: The public URL has no authentication; anyone who obtains the URL can access the target service. Exposing admin panels, database consoles, key services, or unauthenticated write interfaces is prohibited. Only suitable for short-term integration testing; does not support TCP, fixed domains, authentication, long-term operation, or high availability. The public URL must not be treated as confidential—trycloudflare domains can be enumerated, and afterstop the URL becomes invalid immediately, but CDN caches may persist.

Use

SKILL_ROOT="<此 skill 的绝对路径>"

# 启动：必须明确确认公网暴露；默认 12 小时后失效
python3 "$SKILL_ROOT/scripts/run.py" start  --port 11434 --confirm-public --ttl 1800

# 查看同一端口的 tunnel 状态
python3 "$SKILL_ROOT/scripts/run.py" status --port 11434

Verify the public root path, or verify a specified path and content marker

python3 "$SKILL_ROOT/scripts/run.py" verify --port 11434 python3 "$SKILL_ROOT/scripts/run.py" verify --port 11434 --path /api/tags --expect models

Stop immediately when integration testing ends; repeated execution is safe and idempotent

python3 "$SKILL_ROOT/scripts/run.py" stop --port 11434

也可使用 loopback URL：

```bash
python3 "$SKILL_ROOT/scripts/run.py" start --url https://localhost:8443 --no-tls-verify --confirm-public

Parameters

Parameter	Applicable action	Description
--port <1-65535>	All	Local HTTP service port
--url <URL>	All	loopback HTTP(S) URL; mutually exclusive with --port , if both are provided, error and exit 1
--confirm-public	start	Required confirmation; explicitly states that the URL has no authentication
--ttl <秒>	start	Automatic stop time, default 43200(12 hours), range 1–86400, out of range errors and exits 1 (no clamp)
--path <相对路径>	verify	Verification path for this public access, default /
--expect <文本>	verify	Marker that the response body must contain; the body is not output
--timeout <秒>	start	Time to wait for tunnel registration, default 120
--verify-timeout <秒>	verify	Public request timeout, default 20
`--protocol http2	quic`	start
--no-tls-verify	start	Allow local self-signed HTTPS
--schema	Any	Output JSON contract

--port should point to a loopback service port already listening on this machine. If the port is occupied, first confirm whether the target service is actually running, or restart the target service on a different port before exposing it.

Output and lifecycle

• stdout outputs one line of JSON, following the standard envelope {ok, data, error, meta}：
  • Success:ok=true，data contains action/status/local_url/public_url/running/pid/expires_at/verification/stop/stop_command
  • Failure:ok=false，data=null，error contains {code, message, retryable}
• data.status Values:started(new)/running(reuse or status query)/verified/stopped/already_stopped
• esflow node events and error diagnostics are written to stderr and will not pollute stdout for machine reading
• All state is stored only in ~/.cache/port-to-public/<session_hash>/, there are no user artifacts, and no --out
• The same normalized loopback URL maps to the same internal session, so status、verify、stop only needs to repeat the same --port or --url
• After the TTL is reached, the next operation of this skill will clean up the expired tunnel; when integration testing ends, please actively stop
• The session directory is retained after stop for cloudflared.log for later troubleshooting, and the entire session_dir can be deleted manually

Nodes (6)

id	depth	Responsibility
validate_request	0	Parse CLI input parameters, normalize the loopback target,start probe the local service when
inspect_tunnel	1	Read and verify the tunnel state of session_dir, automatically clean up when expired
launch_tunnel	2	Only start: start or reuse Cloudflare Quick Tunnel, write state
stop_tunnel	2	Only stop: stop the process group created by this skill with matching identity
verify_public	3	Only start/verify: public URL path verification, supports the --expect flag
render_result	4	Aggregate upstream artifacts into the stdout envelope's data section

esflow DAG

validate_request → inspect_tunnel → launch_tunnel → verify_public → render_result
                             ├────→ stop_tunnel ────────────────────┘
                             ├────→ launch_tunnel ─→ render_result
                             ├────→ verify_public ──→ render_result
                             └────────────────────→ render_result

Nodes are automatically routed by action :launch_tunnel only start executes,verify_public only start/verify executes,stop_tunnel only stop executes,render_result is always the endpoint.

• start: verify local service → check/reuse session → start tunnel → verify public root path
• status: verify request → check session → output status
• verify: verify request → check session → verify --path
• stop: verify request → check session → only stop the process group created by this skill with matching identity

Exit code

• 0: action succeeded (including already_stopped , the "action completed but no change needed" scenario)
• 1: parameter, dependency, local service, tunnel, or public verification failed

Dependencies

pip dependencies（frontmatter dependencies field):

• esflow

System dependencies(must be installed manually, not a pip package):

brew install cloudflared      # macOS
# apt install cloudflared     # Linux，参考 Cloudflare 官方源

Only macOS / Linux are supported.stop depends on ps -o lstart= for process identity verification, and is unavailable on Windows.