Cassiiopeia/projectops / plugins/projectops-extras/skills/pro-remote-link
pro-remote-link
VerifiedGive one link to open a desktop agent app (Orca, Paseo) on this computer from outside: Orca through a cloudflared quick tunnel and its saved pairing link, Paseo through its relay pairing link. Use for 'Orca link', 'Orca URL', 'Orca tunnel', 'Paseo link', 'remote link', 'open from outside'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.7 KB |
| harness/orca.md | markdown | 3.0 KB |
| harness/paseo.md | markdown | 4.3 KB |
| scripts/remote_apps/__init__.py | script | 961 B |
| scripts/remote_apps/orca.py | script | 1.6 KB |
| scripts/remote_apps/paseo.py | script | 7.5 KB |
| scripts/remote_link_cli.py | script | 11.2 KB |
| scripts/tunnel/__init__.py | script | 105 B |
| scripts/tunnel/links.py | script | 3.2 KB |
| scripts/tunnel/probe.py | script | 2.9 KB |
| scripts/tunnel/proc.py | script | 4.1 KB |
| scripts/tunnel/processes.py | script | 6.5 KB |
| scripts/tunnel/state.py | script | 2.3 KB |
scripts/remote_link_cli.py
View on GitHub#!/usr/bin/env python3
"""remote_link_cli: pro-remote-link one link to open a desktop app from outside — output is always JSON (ok·code·summary·next)
Tunnel apps (Orca): cloudflared quick tunnel open, reuse, cleanup + swap the tunnel host in the saved link
Relay apps (Paseo): the app's own CLI makes a fresh pairing link. Per-app facts live in harness/<app>.md. Standard library only
"""
from __future__ import annotations
import argparse
import json
import os
import sys
import time
import urllib.parse
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
from remote_apps import SUPPORTED_APPS, harness_path # noqa: E402
from tunnel import links, probe, processes, state # noqa: E402
# Time to wait for the new tunnel address to respond (seconds)
ANSWER_WAIT_SECONDS = 40
class _BadArgumentsExit(Exception):
def __init__(self, message):
super().__init__(message)
self.message = message
class JsonArgumentParser(argparse.ArgumentParser):
"""Parser that returns argument errors as JSON instead of stderr"""
def error(self, message):
raise _BadArgumentsExit(message)
def emit(payload: dict) -> int:
payload.setdefault("ok", True)
payload.setdefault("code", "ok" if payload["ok"] else "error")
payload.setdefault("summary", None)
payload.setdefault("next", None)
sys.stdout.write(json.dumps(payload, ensure_ascii=False, default=str) + "\n")
sys.stdout.flush()
return 0 if payload["ok"] else 1
def _local_answers(port: int, path: str) -> bool:
status = probe.local_page(port, path)["status"]
return status is not None and 200 <= status < 400
def _wait_answer(url: str, path: str) -> dict:
deadline = time.time() + ANSWER_WAIT_SECONDS
result = probe.check(url, path)
while not result["answers"] and time.time() < deadline:
time.sleep(2)
result = probe.check(url, path)
return result
# Subcommands: parse input > call module > result + next
def cmd_apps(_args) -> dict:
rows = []
for name, adapter in SUPPORTED_APPS.items():
harness = harness_path(name)
rows.append({"app": name, "connection": adapter.CONNECTION,
"harness": str(harness) if harness else None, **adapter.inspect()})
reachable = [row["app"] for row in rows if row["is_reachable"]]
return {"apps": rows, "summary": f"{len(rows)} supported app(s); reachable from outside now: {', '.join(reachable) or 'none'}",
"next": "link get --app NAME (tunnel apps also need --url from open)"}
def cmd_status(_args) -> dict:
saved = state.load()["tunnels"]
rows = []
for tunnel in processes.quick_tunnels():
record = saved.get(str(tunnel["port"])) or {}
url = record.get("url") if record.get("pid") == tunnel["pid"] else None
rows.append({**tunnel, "url": url, "is_managed": url is not None,
"answers": probe.check(url)["answers"] if url else None})
return {"cloudflared": processes.cloudflared_path(), "tunnels": rows,
"summary": f"{len(rows)} quick tunnel(s) running",
"next": "open --port N to reuse or start one" if rows else "open --port N"}
def cmd_open(args) -> dict:
binary = processes.cloudflared_path()
if not binary:
return {"ok": False, "code": "tool_missing", "summary": "cloudflared is not installed",
"next": "install it: macOS `brew install cloudflared`, Windows `winget install Cloudflare.cloudflared`, then run open again"}
if not _local_answers(args.port, args.path):
return {"ok": False, "code": "local_not_listening",
"summary": f"nothing answers on http://127.0.0.1:{args.port}{args.path}",
"next": "start the app first, or find its port with the harness"}
# Alive and responding > reuse as is
saved = processes.live_tunnel(args.port)
if saved and not args.fresh:
result = probe.check(saved["url"], args.path)
if result["answers"]:
return {"url": saved["url"], "port": args.port, "pid": saved["pid"], "is_reused": True, **result,
"summary": f"reused live tunnel {saved['url']}"}
# Clean up dead or old tunnels on the same port > start a new one
stopped = [tunnel["pid"] for tunnel in processes.quick_tunnels()
if tunnel["port"] == args.port and processes.stop(tunnel["pid"])]
log_path = state.log_path_for(args.port)
pid = processes.start(binary, args.port, log_path)
url = processes.wait_for_url(log_path, pid)
if not url:
return {"ok": False, "code": "no_tunnel_url", "pid": pid, "log": str(log_path),
"summary": "cloudflared started but printed no trycloudflare address",
"next": f"read {log_path}; check the network, then run open again"}
state.remember_tunnel(args.port, pid, url, log_path)
result = _wait_answer(url, args.path)
return {"url": url, "port": args.port, "pid": pid, "is_reused": False, "stopped_pids": stopped, **result,
"ok": result["answers"], "code": "ok" if result["answers"] else "not_answering",
"summary": f"opened {url}" + ("" if result["local_dns_ready"] else " (this Mac's DNS may lag; other devices are fine)"),
"next": None if result["answers"] else f"run `open --port {args.port}` again in a minute"}
def cmd_ports(args) -> dict:
ports = processes.listening_ports_of(args.process)
return {"process": args.process, "ports": ports,
"summary": f"{len(ports)} listening port(s) for processes named like '{args.process}'",
"next": "check each with `local --port N`" if ports else "is the app running?"}
def cmd_local(args) -> dict:
page = probe.local_page(args.port, args.path)
return {"port": args.port, "path": args.path, **page, "ok": page["status"] is not None,
"code": "ok" if page["status"] is not None else "local_not_listening",
"summary": f"{args.port}{args.path}: status {page['status']}, title {page['title']!r}"}
def cmd_stop(args) -> dict:
targets = [tunnel for tunnel in processes.quick_tunnels() if args.all or tunnel["port"] == args.port]
stopped = [tunnel["pid"] for tunnel in targets if processes.stop(tunnel["pid"])]
for tunnel in targets:
state.forget_tunnel(tunnel["port"])
return {"stopped_pids": stopped, "summary": f"stopped {len(stopped)} of {len(targets)} quick tunnel(s)"}
def cmd_link_save(args) -> dict:
adapter = SUPPORTED_APPS.get(args.app)
if adapter and adapter.CONNECTION == "relay":
return {"ok": False, "code": "not_needed", "summary": f"{args.app} makes a fresh link each time; nothing to save",
"next": f"link get --app {args.app}"}
# The link is not taken as a command-line argument (so it doesn't show in the process list)
link = os.environ.get("TUNNEL_LINK", "").strip()
if not link:
return {"ok": False, "code": "no_link", "summary": "TUNNEL_LINK is empty",
"next": "TUNNEL_LINK='<link the user pasted>' ... link save --app NAME"}
links.save(args.app, link)
return {"app": args.app, "summary": f"saved the {args.app} link (owner-only file)"}
def _tunnel_link(args) -> dict:
if not args.url:
return {"ok": False, "code": "url_required", "summary": f"{args.app} is reached through a tunnel; --url is required",
"next": f"open --port N (port from harness/{args.app}.md), then link get --app {args.app} --url <url>"}
link = links.load(args.app)
if not link:
return {"ok": False, "code": "no_saved_link",
"summary": f"no saved {args.app} link",
"next": f"ask the user for one fresh link from the app, then `link save --app {args.app}`"}
new_host = urllib.parse.urlparse(args.url).hostname or ""
updated, replaced = links.retarget(link, new_host)
if replaced == 0:
return {"ok": False, "code": "host_not_found",
"summary": "no trycloudflare address found in the saved link (the app's link format may have changed)",
"next": "follow the harness: ask for a fresh link, save it, and note the change in the harness"}
return {"link": updated, "replaced": replaced, "summary": f"{replaced} address(es) switched to {new_host}"}
def cmd_link_get(args) -> dict:
"""Relay apps > the app's CLI makes the link. Every other app > saved link pointed at the tunnel URL"""
adapter = SUPPORTED_APPS.get(args.app)
if adapter and adapter.CONNECTION == "relay":
return adapter.fresh_link(should_enable_relay=args.enable_relay)
return _tunnel_link(args)
def build_parser() -> JsonArgumentParser:
parser = JsonArgumentParser(prog="remote_link_cli")
commands = parser.add_subparsers(dest="command", required=True, parser_class=JsonArgumentParser)
commands.add_parser("apps").set_defaults(handler=cmd_apps)
commands.add_parser("status").set_defaults(handler=cmd_status)
opener = commands.add_parser("open")
opener.add_argument("--port", type=int, required=True)
opener.add_argument("--path", default="/", help="page to check through the tunnel")
opener.add_argument("--fresh", action="store_true", help="always start a new tunnel")
opener.set_defaults(handler=cmd_open)
porter = commands.add_parser("ports")
porter.add_argument("--process", required=True, help="part of the process name, e.g. orca")
porter.set_defaults(handler=cmd_ports)
local = commands.add_parser("local")
local.add_argument("--port", type=int, required=True)
local.add_argument("--path", default="/")
local.set_defaults(handler=cmd_local)
stopper = commands.add_parser("stop")
target = stopper.add_mutually_exclusive_group(required=True)
target.add_argument("--port", type=int)
target.add_argument("--all", action="store_true")
stopper.set_defaults(handler=cmd_stop)
link = commands.add_parser("link")
link_commands = link.add_subparsers(dest="link_command", required=True, parser_class=JsonArgumentParser)
saver = link_commands.add_parser("save")
saver.add_argument("--app", required=True)
saver.set_defaults(handler=cmd_link_save)
getter = link_commands.add_parser("get")
getter.add_argument("--app", required=True)
getter.add_argument("--url", help="current tunnel URL from `open` (tunnel apps only)")
getter.add_argument("--enable-relay", action="store_true",
help="relay apps: turn the relay on while pairing (only after the user agreed)")
getter.set_defaults(handler=cmd_link_get)
return parser
def main(argv: list[str] | None = None) -> int:
try:
args = build_parser().parse_args(argv)
except _BadArgumentsExit as error:
return emit({"ok": False, "code": "bad_args", "summary": error.message,
"next": "commands: apps, status, ports --process NAME, local --port N, open --port N, stop --port N|--all, link save --app NAME, link get --app NAME [--url URL] [--enable-relay]"})
try:
return emit(args.handler(args))
except Exception as error: # noqa: BLE001 — unexpected exceptions also go out as JSON
return emit({"ok": False, "code": "internal_error", "summary": f"{type(error).__name__}: {error}",
"next": "An unexpected error in the CLI. Report it with pro-skill-bug"})
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |