streamlit-remote 0.1.0__py3-none-any.whl

streamlit_remote/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

streamlit_remote/cli.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import shlex
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+from typing import Sequence
+
+from streamlit_remote.https import (
+    HttpsError,
+    HttpsMaterial,
+    planned_self_signed_material,
+    prepare_https_material,
+)
+from streamlit_remote.process import (
+    ManagedProcess,
+    start_logged_process,
+    terminate_processes,
+    wait_for_process_exit,
+)
+from streamlit_remote.providers import get_provider
+from streamlit_remote.server import LocalServerConfig, is_port_available, wait_until_listening
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="st-remote",
+        description="Run a Streamlit app with optional remote HTTPS access.",
+    )
+    parser.add_argument("app", type=Path, metavar="APP", help="Streamlit app file path.")
+    parser.add_argument("--port", type=int, default=8501, help="Local Streamlit port.")
+    parser.add_argument("--host", default="localhost", help="Local Streamlit host.")
+    parser.add_argument(
+        "--provider",
+        default="cloudflare",
+        choices=["cloudflare", "ngrok"],
+        help="Remote tunnel provider.",
+    )
+    parser.add_argument(
+        "--tunnel-log-level",
+        default="info",
+        choices=["info", "warn", "error", "off"],
+        help="Tunnel provider log verbosity.",
+    )
+    parser.add_argument(
+        "--https",
+        dest="https_mode",
+        default="off",
+        choices=["off", "self-signed", "cert-files"],
+        help="Local Streamlit HTTPS mode.",
+    )
+    parser.add_argument(
+        "--ssl-cert-file",
+        type=Path,
+        help="Existing certificate file for `--https cert-files`.",
+    )
+    parser.add_argument(
+        "--ssl-key-file",
+        type=Path,
+        help="Existing private key file for `--https cert-files`.",
+    )
+    parser.add_argument(
+        "--cert-valid-days",
+        type=int,
+        default=30,
+        help="Validity period for managed self-signed certificates.",
+    )
+    parser.add_argument(
+        "--streamlit-arg",
+        action="append",
+        default=[],
+        help="Extra argument passed to Streamlit. Can be repeated.",
+    )
+    parser.add_argument(
+        "--no-remote",
+        action="store_true",
+        help="Run Streamlit only without starting a remote tunnel.",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not open the local or remote URL in a browser.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print subprocess commands without running them.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print additional diagnostic information.",
+    )
+    return parser
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    cli_args, passthrough_args = split_streamlit_args(argv)
+    namespace = build_parser().parse_args(cli_args)
+    namespace.streamlit_args = [*namespace.streamlit_arg, *passthrough_args]
+    validate_cli_options(namespace)
+    return namespace
+
+
+def split_streamlit_args(argv: Sequence[str]) -> tuple[list[str], list[str]]:
+    args = list(argv)
+    if "--" not in args:
+        return args, []
+
+    separator_index = args.index("--")
+    return args[:separator_index], args[separator_index + 1 :]
+
+
+def build_streamlit_command(
+    app_path: Path,
+    host: str,
+    port: int,
+    streamlit_args: Sequence[str] = (),
+    https_material: HttpsMaterial | None = None,
+) -> list[str]:
+    command = [
+        sys.executable,
+        "-m",
+        "streamlit",
+        "run",
+        str(app_path),
+        "--server.address",
+        host,
+        "--server.port",
+        str(port),
+        "--server.headless",
+        "true",
+    ]
+
+    if https_material is not None:
+        command.extend(
+            [
+                "--server.sslCertFile",
+                str(https_material.cert_file),
+                "--server.sslKeyFile",
+                str(https_material.key_file),
+            ]
+        )
+
+    command.extend(streamlit_args)
+    return command
+
+
+def validate_app_path(app_path: Path) -> None:
+    if not app_path.exists():
+        raise CliError(f"Streamlit app not found: {app_path}")
+
+    if not app_path.is_file():
+        raise CliError(f"Streamlit app path is not a file: {app_path}")
+
+
+def validate_cli_options(namespace: argparse.Namespace) -> None:
+    cert_files = [namespace.ssl_cert_file, namespace.ssl_key_file]
+    if namespace.https_mode != "cert-files" and any(path is not None for path in cert_files):
+        raise CliError(
+            "`--ssl-cert-file` and `--ssl-key-file` can only be used with "
+            "`--https cert-files`."
+        )
+
+
+def require_streamlit() -> None:
+    if importlib.util.find_spec("streamlit") is None:
+        raise CliError(
+            "Streamlit is not installed. Install it with `pip install streamlit` "
+            "or reinstall this package with its dependencies."
+        )
+
+
+def run_cli(argv: Sequence[str] | None = None) -> int:
+    try:
+        namespace = parse_args(sys.argv[1:] if argv is None else argv)
+        return run(namespace)
+    except (CliError, HttpsError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def run(namespace: argparse.Namespace) -> int:
+    validate_app_path(namespace.app)
+
+    scheme = "https" if namespace.https_mode != "off" else "http"
+    local_server = LocalServerConfig(
+        host=namespace.host,
+        port=namespace.port,
+        scheme=scheme,
+    )
+
+    provider = None
+    tunnel_command: list[str] | None = None
+    if not namespace.no_remote:
+        provider = get_provider(namespace.provider)
+        tunnel_command = provider.build_command(
+            local_server.url,
+            origin_tls_verify=namespace.https_mode != "self-signed",
+            tunnel_log_level=namespace.tunnel_log_level,
+        )
+
+    if namespace.dry_run:
+        https_material = prepare_cli_https_material(namespace)
+        streamlit_command = build_streamlit_command(
+            namespace.app,
+            local_server.host,
+            local_server.port,
+            namespace.streamlit_args,
+            https_material=https_material,
+        )
+        print(f"Streamlit command:\n  {shlex.join(streamlit_command)}")
+        if tunnel_command is None:
+            print("Remote access: disabled")
+        else:
+            print(f"Tunnel command:\n  {shlex.join(tunnel_command)}")
+        if namespace.https_mode == "self-signed":
+            print("HTTPS: managed self-signed certificate will be prepared at runtime")
+        return 0
+
+    require_streamlit()
+    if not is_port_available(local_server.host, local_server.port):
+        raise CliError(f"Port {local_server.port} is not available on {local_server.host}.")
+
+    if provider is not None and not provider.is_available():
+        raise CliError(provider.install_hint)
+
+    https_material = prepare_cli_https_material(namespace)
+    streamlit_command = build_streamlit_command(
+        namespace.app,
+        local_server.host,
+        local_server.port,
+        namespace.streamlit_args,
+        https_material=https_material,
+    )
+
+    print("Streamlit local URL:")
+    print(f"  {local_server.url}")
+    if namespace.no_remote:
+        print("\nRemote access: disabled")
+        if not namespace.no_browser:
+            open_browser(local_server.url)
+    else:
+        if namespace.https_mode == "self-signed" and namespace.provider == "ngrok":
+            print(
+                "\nNote: ngrok already provides HTTPS for the public URL. "
+                "Local self-signed HTTPS will be used only between ngrok and Streamlit."
+            )
+        print("\nStarting remote tunnel...")
+
+    remote_url_printed = threading.Event()
+    remote_url_lock = threading.Lock()
+
+    def report_remote_url(public_url: str) -> None:
+        with remote_url_lock:
+            if remote_url_printed.is_set():
+                return
+
+            remote_url_printed.set()
+            print("\nStreamlit local URL:")
+            print(f"  {local_server.url}")
+            print("\nRemote HTTPS URL:")
+            print(f"  {public_url}\n")
+            if not namespace.no_browser:
+                open_browser(public_url)
+
+    def on_tunnel_line(line: str) -> None:
+        if provider is None:
+            return
+
+        public_url = provider.parse_public_url(line)
+        if public_url is not None:
+            report_remote_url(public_url)
+
+    def poll_provider_public_url() -> None:
+        if provider is None:
+            return
+
+        while not remote_url_printed.is_set():
+            public_url = provider.get_public_url()
+            if public_url is not None:
+                report_remote_url(public_url)
+                return
+            time.sleep(0.5)
+
+    handles: list[ManagedProcess] = []
+    public_url_poll_thread: threading.Thread | None = None
+    try:
+        handles.append(start_logged_process(streamlit_command, "streamlit"))
+        if tunnel_command is not None and not wait_until_listening(
+            local_server.host,
+            local_server.port,
+        ):
+            raise CliError(
+                f"Streamlit did not start listening on {local_server.url} within the timeout."
+            )
+
+        if tunnel_command is not None:
+            handles.append(
+                start_logged_process(
+                    tunnel_command,
+                    provider.log_prefix,
+                    on_line=on_tunnel_line,
+                    should_print_line=lambda line: should_print_tunnel_line(
+                        line,
+                        namespace.tunnel_log_level,
+                    ),
+                )
+            )
+            public_url_poll_thread = threading.Thread(
+                target=poll_provider_public_url,
+                name="streamlit-remote-public-url-poll",
+                daemon=True,
+            )
+            public_url_poll_thread.start()
+
+        exited = wait_for_process_exit(handles)
+        return exited.process.returncode if exited.process.returncode is not None else 1
+    except KeyboardInterrupt:
+        print("\nInterrupted. Shutting down child processes...", file=sys.stderr)
+        return 130
+    finally:
+        remote_url_printed.set()
+        terminate_processes(handles)
+        if public_url_poll_thread is not None:
+            public_url_poll_thread.join(timeout=1.0)
+
+
+def main() -> None:
+    raise SystemExit(run_cli())
+
+
+class CliError(Exception):
+    pass
+
+
+def prepare_cli_https_material(namespace: argparse.Namespace) -> HttpsMaterial | None:
+    if namespace.dry_run and namespace.https_mode == "self-signed":
+        return planned_self_signed_material(namespace.host)
+
+    return prepare_https_material(
+        mode=namespace.https_mode,
+        host=namespace.host,
+        cert_file=namespace.ssl_cert_file,
+        key_file=namespace.ssl_key_file,
+        valid_days=namespace.cert_valid_days,
+    )
+
+
+def should_print_tunnel_line(line: str, tunnel_log_level: str) -> bool:
+    if tunnel_log_level == "off":
+        return False
+
+    if tunnel_log_level == "info":
+        return True
+
+    severity = classify_tunnel_line(line)
+    if tunnel_log_level == "warn":
+        return severity in {"warn", "error"}
+
+    if tunnel_log_level == "error":
+        return severity == "error"
+
+    return True
+
+
+def classify_tunnel_line(line: str) -> str:
+    lowered = line.lower()
+    if any(marker in lowered for marker in ("lvl=error", "lvl=crit", " err ", " error", "fatal")):
+        return "error"
+
+    if any(marker in lowered for marker in ("lvl=warn", " wrn ", " warn", "warning")):
+        return "warn"
+
+    return "info"
+
+
+def open_browser(url: str) -> None:
+    try:
+        webbrowser.open(url, new=2)
+    except Exception:
+        pass

streamlit_remote/https.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.x509.oid import NameOID
+
+
+@dataclass(frozen=True)
+class HttpsMaterial:
+    cert_file: Path
+    key_file: Path
+
+
+class HttpsError(Exception):
+    pass
+
+
+def prepare_https_material(
+    mode: str,
+    host: str,
+    cert_file: Path | None = None,
+    key_file: Path | None = None,
+    valid_days: int = 30,
+    cache_dir: Path | None = None,
+) -> HttpsMaterial | None:
+    if mode == "off":
+        return None
+
+    if mode == "cert-files":
+        return validate_cert_files(cert_file, key_file)
+
+    if mode == "self-signed":
+        return prepare_self_signed_material(host, valid_days, cache_dir)
+
+    raise HttpsError(f"Unsupported HTTPS mode: {mode}")
+
+
+def validate_cert_files(
+    cert_file: Path | None,
+    key_file: Path | None,
+) -> HttpsMaterial:
+    if cert_file is None or key_file is None:
+        raise HttpsError(
+            "`--https cert-files` requires both `--ssl-cert-file` and `--ssl-key-file`."
+        )
+
+    if not cert_file.is_file():
+        raise HttpsError(f"SSL certificate file not found: {cert_file}")
+
+    if not key_file.is_file():
+        raise HttpsError(f"SSL key file not found: {key_file}")
+
+    return HttpsMaterial(cert_file=cert_file, key_file=key_file)
+
+
+def prepare_self_signed_material(
+    host: str,
+    valid_days: int = 30,
+    cache_dir: Path | None = None,
+) -> HttpsMaterial:
+    if valid_days < 1:
+        raise HttpsError("`--cert-valid-days` must be at least 1.")
+
+    sans = subject_alt_names_for_host(host)
+    cert_file, key_file, metadata_file = self_signed_paths(host, cache_dir)
+    cert_dir = cert_file.parent
+    cert_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+    if is_reusable_certificate(cert_file, key_file, sans):
+        return HttpsMaterial(cert_file=cert_file, key_file=key_file)
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    now = datetime.now(timezone.utc)
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(certificate_name())
+        .issuer_name(certificate_name())
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - timedelta(minutes=1))
+        .not_valid_after(now + timedelta(days=valid_days))
+        .add_extension(x509.SubjectAlternativeName(sans), critical=False)
+        .sign(key, hashes.SHA256())
+    )
+
+    key_file.write_bytes(
+        key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    os.chmod(key_file, 0o600)
+
+    cert_file.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
+    metadata_file.write_text(
+        json.dumps(
+            {
+                "created_at": now.isoformat(),
+                "expires_at": (now + timedelta(days=valid_days)).isoformat(),
+                "sans": [str(san) for san in sans],
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+    return HttpsMaterial(cert_file=cert_file, key_file=key_file)
+
+
+def planned_self_signed_material(
+    host: str,
+    cache_dir: Path | None = None,
+) -> HttpsMaterial:
+    cert_file, key_file, _ = self_signed_paths(host, cache_dir)
+    return HttpsMaterial(cert_file=cert_file, key_file=key_file)
+
+
+def self_signed_paths(
+    host: str,
+    cache_dir: Path | None = None,
+) -> tuple[Path, Path, Path]:
+    sans = subject_alt_names_for_host(host)
+    cert_dir = cache_dir if cache_dir is not None else default_cert_cache_dir()
+    fingerprint = hashlib.sha256(
+        json.dumps(
+            {
+                "schema": 1,
+                "sans": [str(san) for san in sans],
+            },
+            sort_keys=True,
+        ).encode("utf-8")
+    ).hexdigest()[:16]
+
+    return (
+        cert_dir / f"self-signed-{fingerprint}.crt",
+        cert_dir / f"self-signed-{fingerprint}.key",
+        cert_dir / f"self-signed-{fingerprint}.json",
+    )
+
+
+def default_cert_cache_dir() -> Path:
+    return Path.home() / ".streamlit-remote" / "certs"
+
+
+def subject_alt_names_for_host(host: str) -> list[x509.GeneralName]:
+    names: list[x509.GeneralName] = [
+        x509.DNSName("localhost"),
+        x509.IPAddress(ipaddress.ip_address("127.0.0.1")),
+        x509.IPAddress(ipaddress.ip_address("::1")),
+    ]
+
+    try:
+        host_ip = ipaddress.ip_address(host)
+    except ValueError:
+        if host and host != "localhost":
+            names.append(x509.DNSName(host))
+    else:
+        if host_ip not in {ipaddress.ip_address("127.0.0.1"), ipaddress.ip_address("::1")}:
+            names.append(x509.IPAddress(host_ip))
+
+    return names
+
+
+def is_reusable_certificate(
+    cert_file: Path,
+    key_file: Path,
+    expected_sans: list[x509.GeneralName],
+) -> bool:
+    if not cert_file.is_file() or not key_file.is_file():
+        return False
+
+    try:
+        cert = x509.load_pem_x509_certificate(cert_file.read_bytes())
+        sans = cert.extensions.get_extension_for_class(
+            x509.SubjectAlternativeName
+        ).value
+    except (OSError, ValueError, x509.ExtensionNotFound):
+        return False
+
+    if sorted(str(san) for san in sans) != sorted(str(san) for san in expected_sans):
+        return False
+
+    expires_at = certificate_not_valid_after(cert)
+    return expires_at > datetime.now(timezone.utc) + timedelta(days=1)
+
+
+def certificate_not_valid_after(cert: x509.Certificate) -> datetime:
+    expires_at = getattr(cert, "not_valid_after_utc", None)
+    if expires_at is not None:
+        return expires_at
+    return cert.not_valid_after.replace(tzinfo=timezone.utc)
+
+
+def certificate_name() -> x509.Name:
+    return x509.Name(
+        [
+            x509.NameAttribute(NameOID.COMMON_NAME, "streamlit-remote local development"),
+        ]
+    )

streamlit_remote/process.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+
+LineHandler = Callable[[str], None]
+LinePredicate = Callable[[str], bool]
+
+
+@dataclass
+class ManagedProcess:
+    process: subprocess.Popen[str]
+    prefix: str
+    output_thread: threading.Thread
+
+
+def start_logged_process(
+    command: Sequence[str],
+    prefix: str,
+    on_line: LineHandler | None = None,
+    should_print_line: LinePredicate | None = None,
+) -> ManagedProcess:
+    process = subprocess.Popen(
+        list(command),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        bufsize=1,
+    )
+
+    def pump_output() -> None:
+        if process.stdout is None:
+            return
+
+        for raw_line in process.stdout:
+            line = raw_line.rstrip("\r\n")
+            if should_print_line is None or should_print_line(line):
+                print(f"[{prefix}] {line}", flush=True)
+            if on_line is not None:
+                on_line(line)
+
+    output_thread = threading.Thread(
+        target=pump_output,
+        name=f"streamlit-remote-{prefix}",
+        daemon=True,
+    )
+    output_thread.start()
+    return ManagedProcess(process=process, prefix=prefix, output_thread=output_thread)
+
+
+def wait_for_process_exit(
+    handles: Sequence[ManagedProcess],
+    poll_interval: float = 0.2,
+) -> ManagedProcess:
+    while True:
+        for handle in handles:
+            if handle.process.poll() is not None:
+                return handle
+        time.sleep(poll_interval)
+
+
+def terminate_processes(
+    handles: Sequence[ManagedProcess],
+    terminate_timeout: float = 5.0,
+    kill_timeout: float = 2.0,
+) -> None:
+    for handle in handles:
+        if handle.process.poll() is None:
+            handle.process.terminate()
+
+    deadline = time.monotonic() + terminate_timeout
+    for handle in handles:
+        remaining = max(0.0, deadline - time.monotonic())
+        try:
+            handle.process.wait(timeout=remaining)
+        except subprocess.TimeoutExpired:
+            if handle.process.poll() is None:
+                handle.process.kill()
+
+    for handle in handles:
+        try:
+            handle.process.wait(timeout=kill_timeout)
+        except subprocess.TimeoutExpired:
+            pass
+
+    for handle in handles:
+        handle.output_thread.join(timeout=kill_timeout)

streamlit_remote/providers/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Literal, Protocol
+
+from streamlit_remote.providers.cloudflare import CloudflareQuickTunnelProvider
+from streamlit_remote.providers.ngrok import NgrokProvider
+
+
+TunnelLogLevel = Literal["info", "warn", "error", "off"]
+
+
+class TunnelProvider(Protocol):
+    name: str
+    log_prefix: str
+    install_hint: str
+
+    def build_command(
+        self,
+        local_url: str,
+        *,
+        origin_tls_verify: bool = True,
+        tunnel_log_level: TunnelLogLevel = "info",
+    ) -> list[str]: ...
+
+    def parse_public_url(self, line: str) -> str | None: ...
+
+    def get_public_url(self) -> str | None: ...
+
+    def is_available(self) -> bool: ...
+
+
+def get_provider(name: str) -> TunnelProvider:
+    if name == "cloudflare":
+        return CloudflareQuickTunnelProvider()
+
+    if name == "ngrok":
+        return NgrokProvider()
+
+    raise ValueError(f"Unsupported provider: {name}")

streamlit_remote/providers/cloudflare.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+
+
+TRYCLOUDFLARE_URL_RE = re.compile(r"https://[A-Za-z0-9-]+\.trycloudflare\.com\b")
+
+
+@dataclass(frozen=True)
+class CloudflareQuickTunnelProvider:
+    name: str = "cloudflare"
+    log_prefix: str = "cloudflared"
+    install_hint: str = (
+        "cloudflared was not found on PATH. Install Cloudflare Tunnel from "
+        "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ "
+        "and try again."
+    )
+
+    def build_command(
+        self,
+        local_url: str,
+        *,
+        origin_tls_verify: bool = True,
+        tunnel_log_level: str = "info",
+    ) -> list[str]:
+        command = ["cloudflared", "tunnel", "--url", local_url]
+        if not origin_tls_verify:
+            command.append("--no-tls-verify")
+        return command
+
+    def parse_public_url(self, line: str) -> str | None:
+        match = TRYCLOUDFLARE_URL_RE.search(line)
+        if match is None:
+            return None
+        return match.group(0)
+
+    def get_public_url(self) -> str | None:
+        return None
+
+    def is_available(self) -> bool:
+        return shutil.which("cloudflared") is not None

streamlit_remote/providers/ngrok.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+
+HTTPS_URL_RE = re.compile(r"https://[^\s]+")
+AGENT_API_TUNNELS_URL = "http://127.0.0.1:4040/api/tunnels"
+
+
+@dataclass(frozen=True)
+class NgrokProvider:
+    name: str = "ngrok"
+    log_prefix: str = "ngrok"
+    install_hint: str = (
+        "ngrok was not found on PATH. Install ngrok from "
+        "https://ngrok.com/download and configure your authtoken with "
+        "`ngrok config add-authtoken TOKEN`."
+    )
+
+    def build_command(
+        self,
+        local_url: str,
+        *,
+        origin_tls_verify: bool = True,
+        tunnel_log_level: str = "info",
+    ) -> list[str]:
+        if tunnel_log_level == "off":
+            return ["ngrok", "http", local_url, "--log", "false"]
+
+        return [
+            "ngrok",
+            "http",
+            local_url,
+            "--log",
+            "stdout",
+            "--log-format",
+            "logfmt",
+            "--log-level",
+            tunnel_log_level,
+        ]
+
+    def parse_public_url(self, line: str) -> str | None:
+        if "Forwarding" not in line:
+            return None
+
+        for candidate in HTTPS_URL_RE.findall(line):
+            parsed = urlparse(candidate)
+            if parsed.scheme == "https" and parsed.netloc:
+                return candidate.rstrip(",")
+        return None
+
+    def get_public_url(self) -> str | None:
+        try:
+            with urlopen(AGENT_API_TUNNELS_URL, timeout=0.5) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+
+        return parse_agent_api_public_url(payload)
+
+    def is_available(self) -> bool:
+        return shutil.which("ngrok") is not None
+
+
+def parse_agent_api_public_url(payload: dict[str, Any]) -> str | None:
+    tunnels = payload.get("tunnels")
+    if not isinstance(tunnels, list):
+        return None
+
+    for tunnel in tunnels:
+        if not isinstance(tunnel, dict):
+            continue
+
+        public_url = tunnel.get("public_url")
+        if not isinstance(public_url, str):
+            continue
+
+        parsed = urlparse(public_url)
+        if parsed.scheme == "https" and parsed.netloc:
+            return public_url
+
+    return None

streamlit_remote/server.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import socket
+import time
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LocalServerConfig:
+    host: str
+    port: int
+    scheme: str = "http"
+
+    @property
+    def url(self) -> str:
+        return f"{self.scheme}://{self.host}:{self.port}"
+
+
+def is_port_available(host: str, port: int) -> bool:
+    try:
+        with socket.create_server((host, port), reuse_port=False):
+            return True
+    except OSError:
+        return False
+
+
+def wait_until_listening(
+    host: str,
+    port: int,
+    timeout: float = 20.0,
+    interval: float = 0.2,
+) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=interval):
+                return True
+        except OSError:
+            time.sleep(interval)
+    return False

streamlit_remote-0.1.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: streamlit-remote
+Version: 0.1.0
+Summary: Run Streamlit apps with optional remote HTTPS access.
+Author: Yuichiro Tachibana (Tsuchiya)
+Author-email: Yuichiro Tachibana (Tsuchiya) <t.yic.yt@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Dist: cryptography>=42
+Requires-Dist: streamlit>=1.28
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/whitphx/streamlit-remote
+Project-URL: Repository, https://github.com/whitphx/streamlit-remote
+Project-URL: Issues, https://github.com/whitphx/streamlit-remote/issues
+Description-Content-Type: text/markdown
+
+# streamlit-remote
+
+`streamlit-remote` runs a Streamlit app locally, can serve it over local HTTPS, and can expose it through a temporary remote HTTPS URL.
+
+It supports Cloudflare Quick Tunnel, ngrok, and managed self-signed certificates for local HTTPS. It is meant for development, demos, and temporary sharing, similar in spirit to Slidev's remote access workflow.
+
+## Installation
+
+```bash
+pip install streamlit-remote
+```
+
+This package requires Python 3.10 or newer.
+
+## Basic Usage
+
+```bash
+st-remote app.py
+```
+
+This starts Streamlit on `http://localhost:8501`, starts a Cloudflare Quick Tunnel to that local URL, prefixes logs from both child processes, prints the public `trycloudflare.com` URL once Cloudflare reports it, and opens that remote URL in your browser.
+
+You can also use the alias:
+
+```bash
+streamlit-remote app.py
+```
+
+## Options
+
+```bash
+st-remote APP [--port 8501] [--host localhost] [--https off] [--provider cloudflare]
+```
+
+Useful options:
+
+```bash
+st-remote app.py --port 9000
+st-remote app.py --host 0.0.0.0
+st-remote app.py --no-remote
+st-remote app.py --no-browser
+st-remote app.py --dry-run
+st-remote app.py --https self-signed --no-remote
+st-remote app.py --provider ngrok
+st-remote app.py --provider ngrok --tunnel-log-level warn
+st-remote app.py -- --server.headless true
+```
+
+Extra arguments after `--` are passed to `python -m streamlit run`.
+
+`st-remote` starts Streamlit in headless mode so Streamlit does not open the local URL automatically. When remote access is enabled, `st-remote` opens the detected remote HTTPS URL instead. Use `--no-browser` to suppress browser opening.
+
+## Local HTTPS
+
+By default, Streamlit runs locally over HTTP:
+
+```bash
+st-remote app.py --https off
+```
+
+For local HTTPS, use managed self-signed mode:
+
+```bash
+st-remote app.py --https self-signed --no-remote
+```
+
+`streamlit-remote` creates and reuses a local development certificate in its own cache directory, then passes Streamlit's `server.sslCertFile` and `server.sslKeyFile` options automatically. You do not need to choose filenames or manage generated certificate files.
+
+Browsers generally do not trust self-signed certificates by default. You may see a certificate warning unless you manually trust the generated certificate. This mode is intended for local development and testing, not production.
+
+Advanced users can pass existing certificate files:
+
+```bash
+st-remote app.py --https cert-files \
+  --ssl-cert-file cert.pem \
+  --ssl-key-file key.pem
+```
+
+## Remote Providers
+
+### Cloudflare Tunnel
+
+Cloudflare Quick Tunnel requires the `cloudflared` command to be installed and available on `PATH`.
+
+Install instructions are available from Cloudflare:
+
+https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
+
+`streamlit-remote` checks for `cloudflared` before starting the tunnel and prints an actionable error if it is missing. It does not install `cloudflared` automatically.
+
+### ngrok
+
+ngrok requires the `ngrok` command to be installed and available on `PATH`.
+
+Install instructions are available from ngrok:
+
+https://ngrok.com/download
+
+Configure your ngrok account token before use:
+
+```bash
+ngrok config add-authtoken TOKEN
+```
+
+Then run:
+
+```bash
+st-remote app.py --provider ngrok
+```
+
+ngrok provides HTTPS for the public URL while forwarding to your local Streamlit app. If you combine ngrok with local self-signed HTTPS:
+
+```bash
+st-remote app.py --provider ngrok --https self-signed
+```
+
+ngrok still provides HTTPS for the public URL. The self-signed certificate is used only between the local ngrok agent and Streamlit.
+
+## Tunnel Logs
+
+Tunnel provider logs are shown by default:
+
+```bash
+st-remote app.py --tunnel-log-level info
+```
+
+Use a quieter level to reduce provider noise while keeping Streamlit logs visible:
+
+```bash
+st-remote app.py --provider ngrok --tunnel-log-level warn
+st-remote app.py --provider ngrok --tunnel-log-level error
+st-remote app.py --provider ngrok --tunnel-log-level off
+```
+
+`off` suppresses printed tunnel logs but still captures provider output internally when needed to detect the remote URL. ngrok also uses its local agent API as a fallback for URL detection.
+
+## HTTPS Serving vs Remote Access
+
+The design treats HTTPS serving and remote access as separate concepts.
+
+HTTPS serving means the user-facing URL uses HTTPS. Remote access means the app is reachable from outside your local machine.
+
+Cloudflare Quick Tunnel and ngrok usually provide both at once: Streamlit can run locally over plain HTTP, while the provider gives you a public HTTPS URL that forwards to the local app.
+
+Local self-signed HTTPS is different: Streamlit itself runs with HTTPS locally. You can use this without remote access, or combine it with a remote provider when you specifically want HTTPS between the tunnel agent and Streamlit.
+
+Common combinations:
+
+```text
+--https off + --provider cloudflare
+  Public HTTPS via Cloudflare, local HTTP Streamlit.
+
+--https off + --provider ngrok
+  Public HTTPS via ngrok, local HTTP Streamlit.
+
+--https self-signed + --no-remote
+  Local HTTPS Streamlit only.
+
+--https self-signed + --provider ngrok
+  Public HTTPS via ngrok, local HTTPS between ngrok and Streamlit.
+```
+
+For managed self-signed HTTPS with Cloudflare Tunnel, `streamlit-remote` also passes Cloudflare's origin TLS verification flag automatically so `cloudflared` can connect to the local self-signed Streamlit server.
+
+## Security
+
+This exposes a local Streamlit app to the internet.
+
+Do not use it for sensitive data unless you have proper authentication and access control in place. Cloudflare Quick Tunnel and ngrok are best suited for development, demos, and temporary sharing.
+
+Streamlit's built-in SSL configuration is useful for local testing, but it is not a replacement for a production HTTPS reverse proxy.
+
+## Limitations
+
+The current package does not include mkcert integration, production Cloudflare named tunnels, authentication, password protection, reverse proxy management, or PyPI publishing automation.
+
+## Roadmap
+
+- local HTTPS with mkcert
+- optional auth and access-control integration
+
+## Development
+
+```bash
+uv run pytest
+```
+
+## Release Management
+
+This project uses `scriv-release` for changelog-fragment based releases.
+
+For user-visible changes, add a fragment:
+
+```bash
+uv run scriv create --edit
+```
+
+When fragments are merged to `main`, the release workflow opens or updates a changelog preview PR. Merging that preview PR tags the release. Tag pushes matching `v*` run the PyPI publish workflow through Trusted Publishing.
+
+The release workflow expects a GitHub App configured through `RELEASE_APP_CLIENT_ID` and `RELEASE_APP_KEY` so release tags can trigger the downstream publish workflow.

streamlit_remote-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+streamlit_remote/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+streamlit_remote/cli.py,sha256=uf06kpaEezoc5oWd0u0UR-uJaIwrrvyP8x-_E7lOkeQ,11873
+streamlit_remote/https.py,sha256=rHzSqN8EBHnoFb3sKHr_89sbhgLvv3wWU4l-yyE7Rsc,6159
+streamlit_remote/process.py,sha256=OzlrTNWpoDYFO3X-1SI4drz5_jF0CKad17pY4W16Fww,2467
+streamlit_remote/providers/__init__.py,sha256=u7PY69vMMHFB4M_joExxqnSmDjECQ7YhQJoWequ03dk,938
+streamlit_remote/providers/cloudflare.py,sha256=zZlfSSHSOx1ZmZOQrg0vSoGWdF79GtXoz3ahdi_jjag,1225
+streamlit_remote/providers/ngrok.py,sha256=zqCsAmv406W9u6GpFH77F_rRHJELVnhfHmd9LcIe5DU,2395
+streamlit_remote/server.py,sha256=NotodxzLQQkscDJrPD_JsmrzyFDvNXaShDUjPHFqtGk,889
+streamlit_remote-0.1.0.dist-info/licenses/LICENSE,sha256=xsfsjT1anhkYpYTUBK5AzuBgCSVwGxIqG0_5sVSy1Xk,1086
+streamlit_remote-0.1.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+streamlit_remote-0.1.0.dist-info/entry_points.txt,sha256=_tb74_eGe-Mloy8jT3rZrswZHR1VkHMgAX4HWpz7vqk,102
+streamlit_remote-0.1.0.dist-info/METADATA,sha256=6h4LcCs6G3YPerx2_yRbPC9tHicBRXX10zgymowyffU,7754
+streamlit_remote-0.1.0.dist-info/RECORD,,

streamlit_remote-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.19
+Root-Is-Purelib: true
+Tag: py3-none-any

streamlit_remote-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+st-remote = streamlit_remote.cli:main
+streamlit-remote = streamlit_remote.cli:main
+

streamlit_remote-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuichiro Tachibana (Tsuchiya)
+
+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.