runtime-sdk 0.4.9__tar.gz → 0.4.11__tar.gz

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-sdk
-Version: 0.4.9
+Version: 0.4.11
 Summary: Runtime Python SDK and CLI
 Project-URL: Repository, https://github.com/The-Money-Company-Limited/runtimevm
 Project-URL: Issues, https://github.com/The-Money-Company-Limited/runtimevm/issues
@@ -54,16 +54,27 @@ runtime logout
 runtime login --api-key rt_live_...
 
 # Computers
-runtime create                       # in a real TTY, creates then drops you into the console
+runtime create                       # creates a computer with the starter app already published
 runtime create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
 runtime enter <name-or-id>         # accepts slug/name like test, or the computer id
 runtime list
 runtime info <id>
 runtime start <id>
-runtime run <id> "echo hello"
+runtime run <id> "echo hello"      # one-shot foreground command only
 runtime run <id> "apt install -y nodejs" --uid 0
-runtime publish <id> 3000
+runtime startup show <id>
+runtime startup set <id> --command "python3 app.py" --cwd /home/ubuntu --port 3000
+runtime startup clear <id>          # low-level durable service config
+runtime service show <id>           # user-facing alias for the durable published app
+runtime service clear <id>
+runtime publish <id> 3000           # promote the running app on port 3000 to the public durable app
 runtime delete <id>
+
+# Inside a running computer, the helper installed by Runtime can manage the
+# durable app without leaving the sandbox:
+#   runtime-env publish 3000
+#   runtime-env service show
+#   runtime-env service clear
 ```
 
 ## Python
@@ -73,12 +84,12 @@ from runtime_sdk import RuntimeClient
 
 client = RuntimeClient(base_url="https://api.runruntime.dev", api_key="rt_live_...")
 
-# Create a computer
+# Create a computer. New computers start with the starter app already published.
 computer = client.create_computer()
 print(computer["public_url"])  # https://goldbird.runruntime.dev
 
-# Or create one with a durable startup command.
-# That startup config is replayed after cold restore / auto-wake.
+# Or create one with an explicit durable app command.
+# That saved service is replayed after cold restore / start.
 app = client.create_computer(
     slug="myapp",
     command="python3 app.py",
@@ -93,7 +104,8 @@ print(result["stdout"])
 # Wake a cold computer explicitly
 client.start_computer(app["id"])
 
-# Pin the public URL to a local app port
+# Promote the running app on a local port to the durable public app.
+# Runtime inspects the listening process and saves its command + cwd when possible.
 client.publish_port(computer["id"], 3000)
 
 # List, info, delete
@@ -120,10 +132,16 @@ make smoke
 Use `make deploy` instead of `make sync` when migrations, env
 files, Caddy, or systemd units changed.
 
-Cold restore and public auto-wake replay the saved startup command only for
-computers created with `--command` + `--port` (or the SDK `command`/`port`
-arguments). If you start an app later via a one-off `runtime run`, the
-filesystem is restored after going cold, but that ad-hoc process is not.
+Cold restore and explicit `runtime start` replay the saved published app command.
+New computers seed that durable app from the starter workspace. Later,
+`runtime publish <id> <port>` can promote a running listener into the saved
+public app definition by inspecting the live process. Inside a running computer,
+`runtime-env publish <port>` does the same thing using a computer-scoped token
+installed by Runtime. `runtime service show|clear` and `runtime-env service
+show|clear` expose that same durable app state directly. The low-level
+`runtime startup ...` commands still map to the same durable state. A one-off
+`runtime run` stays one-shot: the filesystem is restored after going cold, but
+that ad-hoc process is not.
 
 Run the SDK unit tests through the backend project environment:
 

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/README.md

@@ -35,16 +35,27 @@ runtime logout
 runtime login --api-key rt_live_...
 
 # Computers
-runtime create                       # in a real TTY, creates then drops you into the console
+runtime create                       # creates a computer with the starter app already published
 runtime create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
 runtime enter <name-or-id>         # accepts slug/name like test, or the computer id
 runtime list
 runtime info <id>
 runtime start <id>
-runtime run <id> "echo hello"
+runtime run <id> "echo hello"      # one-shot foreground command only
 runtime run <id> "apt install -y nodejs" --uid 0
-runtime publish <id> 3000
+runtime startup show <id>
+runtime startup set <id> --command "python3 app.py" --cwd /home/ubuntu --port 3000
+runtime startup clear <id>          # low-level durable service config
+runtime service show <id>           # user-facing alias for the durable published app
+runtime service clear <id>
+runtime publish <id> 3000           # promote the running app on port 3000 to the public durable app
 runtime delete <id>
+
+# Inside a running computer, the helper installed by Runtime can manage the
+# durable app without leaving the sandbox:
+#   runtime-env publish 3000
+#   runtime-env service show
+#   runtime-env service clear
 ```
 
 ## Python
@@ -54,12 +65,12 @@ from runtime_sdk import RuntimeClient
 
 client = RuntimeClient(base_url="https://api.runruntime.dev", api_key="rt_live_...")
 
-# Create a computer
+# Create a computer. New computers start with the starter app already published.
 computer = client.create_computer()
 print(computer["public_url"])  # https://goldbird.runruntime.dev
 
-# Or create one with a durable startup command.
-# That startup config is replayed after cold restore / auto-wake.
+# Or create one with an explicit durable app command.
+# That saved service is replayed after cold restore / start.
 app = client.create_computer(
     slug="myapp",
     command="python3 app.py",
@@ -74,7 +85,8 @@ print(result["stdout"])
 # Wake a cold computer explicitly
 client.start_computer(app["id"])
 
-# Pin the public URL to a local app port
+# Promote the running app on a local port to the durable public app.
+# Runtime inspects the listening process and saves its command + cwd when possible.
 client.publish_port(computer["id"], 3000)
 
 # List, info, delete
@@ -101,10 +113,16 @@ make smoke
 Use `make deploy` instead of `make sync` when migrations, env
 files, Caddy, or systemd units changed.
 
-Cold restore and public auto-wake replay the saved startup command only for
-computers created with `--command` + `--port` (or the SDK `command`/`port`
-arguments). If you start an app later via a one-off `runtime run`, the
-filesystem is restored after going cold, but that ad-hoc process is not.
+Cold restore and explicit `runtime start` replay the saved published app command.
+New computers seed that durable app from the starter workspace. Later,
+`runtime publish <id> <port>` can promote a running listener into the saved
+public app definition by inspecting the live process. Inside a running computer,
+`runtime-env publish <port>` does the same thing using a computer-scoped token
+installed by Runtime. `runtime service show|clear` and `runtime-env service
+show|clear` expose that same durable app state directly. The low-level
+`runtime startup ...` commands still map to the same durable state. A one-off
+`runtime run` stays one-shot: the filesystem is restored after going cold, but
+that ad-hoc process is not.
 
 Run the SDK unit tests through the backend project environment:
 

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runtime-sdk"
-version = "0.4.9"
+version = "0.4.11"
 description = "Runtime Python SDK and CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/scripts/runtime_sdk/cli.py

@@ -5,12 +5,18 @@ import contextlib
 import json
 import os
 import select
+import shlex
 import shutil
+import signal
+import socket
+import subprocess
 import sys
 import termios
 import threading
+import time
 import tty
 from datetime import datetime, timezone
+from pathlib import Path
 from typing import Any, Callable
 from urllib.parse import urljoin, urlparse
 
@@ -159,16 +165,16 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("whoami")
     subparsers.add_parser("logout")
 
-    create_cmd = subparsers.add_parser("create", help="Create a new computer")
+    create_cmd = subparsers.add_parser("create", help="Create a new computer with the starter app published by default")
     create_cmd.add_argument(
         "name",
         nargs="?",
         default=None,
         help="Subdomain name (e.g. redsox → redsox.runruntime.dev). Random if skipped.",
     )
-    create_cmd.add_argument("--command", dest="startup_command", help="App startup command to run after create")
-    create_cmd.add_argument("--cwd", help="Working directory for the startup command")
-    create_cmd.add_argument("--port", type=int, help="App port to publish after startup")
+    create_cmd.add_argument("--command", dest="startup_command", help="Durable startup command to save on create")
+    create_cmd.add_argument("--cwd", help="Working directory for the durable startup command")
+    create_cmd.add_argument("--port", type=int, help="App port to publish for durable startup")
     subparsers.add_parser("list", aliases=["ls"], help="List computers")
 
     enter_cmd = subparsers.add_parser("enter", help="Enter a computer's console")
@@ -177,13 +183,16 @@ def build_parser() -> argparse.ArgumentParser:
     info_cmd = subparsers.add_parser("info", help="Get computer details")
     info_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
 
+    url_cmd = subparsers.add_parser("url", help="Show a computer's public URL and live published port")
+    url_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
     start_cmd = subparsers.add_parser("start", help="Wake a cold computer")
     start_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
 
     delete_cmd = subparsers.add_parser("delete", aliases=["rm"], help="Delete a computer")
     delete_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
 
-    run_cmd = subparsers.add_parser("run", help="Run a command in a computer")
+    run_cmd = subparsers.add_parser("run", help="Run a one-shot command in a computer")
     run_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
     run_cmd.add_argument(
         "run_command",
@@ -198,11 +207,47 @@ def build_parser() -> argparse.ArgumentParser:
     run_cmd.add_argument("--shell", help="Shell to use")
 
     publish_cmd = subparsers.add_parser(
-        "publish", help="Pin the public URL to a local app port"
+        "publish", help="Promote the running app on a local port into the durable public app"
     )
     publish_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
     publish_cmd.add_argument("port", nargs="?", type=int, default=None, help="Local app port")
 
+    startup_cmd = subparsers.add_parser("startup", help="Manage durable startup config")
+    startup_subparsers = startup_cmd.add_subparsers(dest="startup_action", required=True)
+    startup_show = startup_subparsers.add_parser("show", help="Show durable startup config")
+    startup_show.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    startup_set = startup_subparsers.add_parser("set", help="Set durable startup config")
+    startup_set.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    startup_set.add_argument("--command", dest="startup_value_command", required=True, help="Durable startup command")
+    startup_set.add_argument("--cwd", help="Working directory for the durable startup command")
+    startup_set.add_argument("--port", required=True, type=int, help="App port to publish for durable startup")
+    startup_clear = startup_subparsers.add_parser("clear", help="Clear durable startup config")
+    startup_clear.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    service_cmd = subparsers.add_parser("service", help="Manage the durable published app service")
+    service_subparsers = service_cmd.add_subparsers(dest="service_action", required=True)
+    service_show = service_subparsers.add_parser("show", help="Show the durable published app service")
+    service_show.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_clear = service_subparsers.add_parser("clear", help="Clear the durable published app service")
+    service_clear.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    proxy_cmd = subparsers.add_parser("proxy", help="Manage background local port proxies")
+    proxy_subparsers = proxy_cmd.add_subparsers(dest="proxy_command", required=True)
+    proxy_start = proxy_subparsers.add_parser("start", help="Start one or more background local port proxies")
+    proxy_start.add_argument("id", help="Computer ID (hostname)")
+    proxy_start.add_argument("ports", nargs="+", help="Port mappings like 5432 or 15432:5432")
+    proxy_subparsers.add_parser("ls", help="List background local port proxies")
+    proxy_stop = proxy_subparsers.add_parser("stop", help="Stop one or more background local port proxies")
+    proxy_stop.add_argument("local_ports", nargs="*", type=int, help="Local ports to stop")
+    proxy_stop.add_argument("--all", action="store_true", help="Stop all running proxies")
+
+    proxy_agent = subparsers.add_parser("_proxy_agent", help=argparse.SUPPRESS)
+    proxy_agent.add_argument("--base-url", required=True)
+    proxy_agent.add_argument("--computer-id", required=True)
+    proxy_agent.add_argument("--display-name", required=True)
+    proxy_agent.add_argument("--local-port", type=int, required=True)
+    proxy_agent.add_argument("--remote-port", type=int, required=True)
+
     return parser
 
 
@@ -247,6 +292,8 @@ def main(argv: list[str] | None = None) -> int:
             return handle_list(config)
         if args.command == "info":
             return handle_info(config, args.id)
+        if args.command == "url":
+            return handle_url(config, args.id)
         if args.command == "start":
             return handle_start(config, args.id)
         if args.command == "enter":
@@ -259,6 +306,37 @@ def main(argv: list[str] | None = None) -> int:
             )
         if args.command == "publish":
             return handle_publish(config, args.id, args.port)
+        if args.command == "startup":
+            if args.startup_action == "show":
+                return handle_startup_show(config, args.id)
+            if args.startup_action == "set":
+                return handle_startup_set(config, args.id, args.startup_value_command, args.cwd, args.port)
+            if args.startup_action == "clear":
+                return handle_startup_clear(config, args.id)
+            return report_error("unknown startup command")
+        if args.command == "service":
+            if args.service_action == "show":
+                return handle_service_show(config, args.id)
+            if args.service_action == "clear":
+                return handle_service_clear(config, args.id)
+            return report_error("unknown service command")
+        if args.command == "proxy":
+            if args.proxy_command == "start":
+                return handle_proxy_start(config, args.id, args.ports)
+            if args.proxy_command == "ls":
+                return handle_proxy_ls(config)
+            if args.proxy_command == "stop":
+                return handle_proxy_stop(config, args.local_ports, stop_all=args.all)
+            return report_error("unknown proxy command")
+        if args.command == "_proxy_agent":
+            return run_proxy_agent(
+                args.base_url,
+                os.environ.get("RUNTIME_PROXY_API_KEY", ""),
+                args.computer_id,
+                args.display_name,
+                args.local_port,
+                args.remote_port,
+            )
     except RuntimeAPIError as exc:
         return report_error(str(exc), status_code=exc.status_code)
     except RuntimeConfigError as exc:
@@ -311,6 +389,201 @@ def _require_api_key(config: RuntimeConfig) -> int | None:
     return report_error("missing api key; run login or verify first")
 
 
+def _runtime_state_dir() -> Path:
+    root = os.environ.get("XDG_STATE_HOME")
+    if root:
+        return Path(root) / "runtime"
+    return Path.home() / ".local" / "state" / "runtime"
+
+
+def _proxy_dir() -> Path:
+    return _runtime_state_dir() / "proxies"
+
+
+def _proxy_state_path(local_port: int) -> Path:
+    return _proxy_dir() / f"proxy-{local_port}.json"
+
+
+def _proxy_log_path(local_port: int) -> Path:
+    return _proxy_dir() / f"proxy-{local_port}.log"
+
+
+def _pid_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def _pid_command(pid: int) -> str:
+    if pid <= 0:
+        return ""
+    try:
+        return subprocess.check_output(
+            ["ps", "-o", "command=", "-p", str(pid)],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _proxy_pid_matches(pid: int, local_port: int) -> bool:
+    if not _pid_running(pid):
+        return False
+    command = _pid_command(pid)
+    if not command:
+        return False
+    with contextlib.suppress(ValueError):
+        argv = shlex.split(command)
+        if "_proxy_agent" not in argv:
+            return False
+        if "--local-port" not in argv:
+            return False
+        index = argv.index("--local-port")
+        if index + 1 >= len(argv) or argv[index + 1] != str(local_port):
+            return False
+        return "runtime_sdk.cli" in argv or any(part.endswith("runtime_sdk.cli") for part in argv)
+    return False
+
+
+def _load_proxy_records(*, clean_stale: bool = False) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    directory = _proxy_dir()
+    if not directory.exists():
+        return records
+    for path in sorted(directory.glob("proxy-*.json")):
+        try:
+            record = json.loads(path.read_text())
+        except (OSError, ValueError):
+            continue
+        if not isinstance(record, dict):
+            continue
+        record["state_path"] = str(path)
+        pid = int(record.get("pid") or 0)
+        local_port = int(record.get("local_port") or 0)
+        record["status"] = "running" if _proxy_pid_matches(pid, local_port) else "stopped"
+        if clean_stale and record["status"] != "running":
+            with contextlib.suppress(OSError):
+                path.unlink()
+            continue
+        records.append(record)
+    return records
+
+
+def _parse_proxy_port_spec(spec: str) -> tuple[int, int]:
+    text = str(spec or "").strip()
+    if not text:
+        raise RuntimeAPIError("port mapping is required")
+    if ":" in text:
+        local_text, remote_text = text.split(":", 1)
+    else:
+        local_text, remote_text = text, text
+    try:
+        local_port = int(local_text)
+        remote_port = int(remote_text)
+    except ValueError as exc:
+        raise RuntimeAPIError(f"invalid port mapping: {text}") from exc
+    for port in (local_port, remote_port):
+        if port <= 0 or port > 65535:
+            raise RuntimeAPIError("port must be between 1 and 65535")
+    return local_port, remote_port
+
+
+def _resolve_ws_url(base_url: str, ws_url: Any) -> str:
+    text = str(ws_url or "").strip()
+    if not text:
+        return ""
+    if text.startswith("ws://") or text.startswith("wss://"):
+        return text
+
+    parsed = urlparse(base_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    root = f"{scheme}://{parsed.netloc}"
+    if text.startswith("/"):
+        return root + text
+    return urljoin(root + "/", text)
+
+
+def _spawn_proxy_agent(base_url: str, api_key: str, computer_id: str, display_name: str, local_port: int, remote_port: int) -> int:
+    proxy_dir = _proxy_dir()
+    proxy_dir.mkdir(parents=True, exist_ok=True)
+    log_path = _proxy_log_path(local_port)
+    log_file = log_path.open("a", encoding="utf-8")
+    child_env = os.environ.copy()
+    child_env["RUNTIME_PROXY_API_KEY"] = api_key
+    try:
+        proc = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "runtime_sdk.cli",
+                "_proxy_agent",
+                "--base-url",
+                base_url,
+                "--computer-id",
+                computer_id,
+                "--display-name",
+                display_name,
+                "--local-port",
+                str(local_port),
+                "--remote-port",
+                str(remote_port),
+            ],
+            stdin=subprocess.DEVNULL,
+            stdout=log_file,
+            stderr=log_file,
+            start_new_session=True,
+            close_fds=True,
+            env=child_env,
+        )
+    finally:
+        log_file.close()
+
+    deadline = time.time() + 4.0
+    state_path = _proxy_state_path(local_port)
+    while time.time() < deadline:
+        if state_path.exists():
+            return proc.pid
+        code = proc.poll()
+        if code is not None:
+            break
+        time.sleep(0.1)
+
+    message = f"proxy failed to start on localhost:{local_port}"
+    with contextlib.suppress(OSError):
+        tail = log_path.read_text(encoding="utf-8").strip()
+        if tail:
+            message = tail.splitlines()[-1]
+    raise RuntimeAPIError(message)
+
+
+def _remove_proxy_state(local_port: int) -> None:
+    with contextlib.suppress(OSError):
+        _proxy_state_path(local_port).unlink()
+
+
+def _stop_proxy_ports(local_ports: list[int], *, stop_all: bool = False) -> list[dict[str, Any]]:
+    records = _load_proxy_records(clean_stale=False)
+    stopped: list[dict[str, Any]] = []
+    wanted = set(local_ports)
+    for record in records:
+        port = int(record.get("local_port") or 0)
+        if not stop_all and port not in wanted:
+            continue
+        pid = int(record.get("pid") or 0)
+        if _proxy_pid_matches(pid, port):
+            with contextlib.suppress(OSError):
+                os.kill(pid, signal.SIGTERM)
+        _remove_proxy_state(port)
+        record["status"] = "stopped"
+        stopped.append(record)
+    return stopped
+
+
 def _prompt_text(message: str, *, default: str | None = None) -> str | None:
     """Ask for a line of text. Returns None if the user left it blank.
 
@@ -424,7 +697,7 @@ def _resolve_computer_ref(client: RuntimeClient, ref: str) -> str:
         return resolved or ref
     if len(matches) > 1:
         raise RuntimeAPIError(f"multiple computers matched {ref!r}; use the exact computer id")
-    return ref
+    raise RuntimeAPIError(f"computer {ref!r} not found")
 
 
 
@@ -732,6 +1005,54 @@ def _render_run_result(result: dict[str, Any]) -> None:
     console.print(f"[{color}]exit {exit_code}[/{color}]")
 
 
+def _render_network_panel(payload: dict[str, Any], *, title: str = "url") -> None:
+    mods = _UI.rich()
+    Panel, Text = mods["Panel"], mods["Text"]
+    body = Text()
+    status = str(payload.get("status") or "unknown")
+    published_port = payload.get("published_port")
+    startup_port = payload.get("startup_port")
+    rows: list[tuple[str, str, str | None]] = [
+        ("url", str(payload.get("public_url") or "—"), "cyan"),
+        ("state", f"{_computer_status_dot(status)} {status}", _computer_status_style(status)),
+    ]
+    if published_port:
+        rows.append(("port", str(published_port), "bold white"))
+    elif startup_port:
+        rows.append(("port", str(startup_port), "bold white"))
+        rows.append(("source", "durable startup", "dim"))
+    else:
+        rows.append(("port", "—", "dim"))
+    if published_port and startup_port and startup_port != published_port:
+        rows.append(("startup", str(startup_port), "dim"))
+    for label, value, style in rows:
+        body.append(f"{label:<8}", style="dim")
+        body.append(value, style=style or "white")
+        body.append("\n")
+    _UI.console().print(Panel(body, title=title, border_style="cyan", expand=False, padding=(0, 1)))
+
+
+def _render_startup_panel(payload: dict[str, Any], *, title: str = "startup") -> None:
+    mods = _UI.rich()
+    Panel, Text = mods["Panel"], mods["Text"]
+    body = Text()
+    configured = bool(payload.get("configured"))
+    rows: list[tuple[str, str, str | None]] = [("configured", "yes" if configured else "no", "bold white" if configured else "dim")]
+    if configured:
+        rows.extend(
+            [
+                ("command", str(payload.get("command") or "—"), "white"),
+                ("cwd", str(payload.get("cwd") or "/home/ubuntu"), "dim"),
+                ("port", str(payload.get("port") or "—"), "bold white"),
+            ]
+        )
+    for label, value, style in rows:
+        body.append(f"{label:<10}", style="dim")
+        body.append(value, style=style or "white")
+        body.append("\n")
+    _UI.console().print(Panel(body, title=title, border_style="cyan", expand=False, padding=(0, 1)))
+
+
 def _render_whoami_panel(payload: dict[str, Any]) -> None:
     mods = _UI.rich()
     Panel, Text = mods["Panel"], mods["Text"]
@@ -973,6 +1294,131 @@ def handle_info(config: RuntimeConfig, computer_id: str | None) -> int:
     return report_success(result, lambda p: _render_computer_panel(p, title="computer"))
 
 
+def handle_url(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not _interactive():
+            return report_error("computer id is required")
+        picked = _pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return report_error("computer is missing an id")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = client.get_computer_network(computer_id)
+    return report_success(result, lambda p: _render_network_panel(p, title="url"))
+
+
+def handle_startup_show(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not _interactive():
+            return report_error("computer id is required")
+        picked = _pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return report_error("computer is missing an id")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = client.get_startup_config(computer_id)
+    return report_success(result, lambda p: _render_startup_panel(p, title="startup"))
+
+
+def handle_startup_set(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    command: str | None,
+    cwd: str | None,
+    port: int | None,
+) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if not computer_id:
+        return report_error("computer id is required")
+    if not command:
+        return report_error("startup command is required")
+    if port is None:
+        return report_error("port is required")
+    if port <= 0 or port > 65535:
+        return report_error("port must be between 1 and 65535")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = _with_spinner(
+        f"saving startup config for {computer_id}…",
+        lambda: client.set_startup_config(computer_id, command=command, cwd=cwd, port=port),
+    )
+    return report_success(result, lambda p: _render_startup_panel(p, title="startup saved"))
+
+
+def handle_startup_clear(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if not computer_id:
+        return report_error("computer id is required")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = _with_spinner(
+        f"clearing startup config for {computer_id}…",
+        lambda: client.clear_startup_config(computer_id),
+    )
+
+    def render(_: dict[str, Any]) -> None:
+        _UI.console().print(f"[green]✓[/green] cleared durable startup config for [bold]{computer_id}[/bold]")
+
+    return report_success(result or {"configured": False}, render)
+
+
+def handle_service_show(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not _interactive():
+            return report_error("computer id is required")
+        picked = _pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return report_error("computer is missing an id")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = client.get_service_config(computer_id)
+    return report_success(result, lambda p: _render_startup_panel(p, title="service"))
+
+
+def handle_service_clear(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if not computer_id:
+        return report_error("computer id is required")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    computer_id = _resolve_computer_ref(client, computer_id)
+    result = _with_spinner(
+        f"clearing service for {computer_id}…",
+        lambda: client.clear_service_config(computer_id),
+    )
+
+    def render(_: dict[str, Any]) -> None:
+        _UI.console().print(f"[green]✓[/green] cleared durable service for [bold]{computer_id}[/bold]")
+
+    return report_success(result or {"configured": False}, render)
+
+
 def handle_start(config: RuntimeConfig, computer_id: str | None) -> int:
     if (err := _require_api_key(config)) is not None:
         return err
@@ -1139,24 +1585,239 @@ def handle_publish(config: RuntimeConfig, computer_id: str | None, port: int | N
 
     client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
     computer_id = _resolve_computer_ref(client, computer_id)
-    _with_spinner(
+    result = _with_spinner(
         f"publishing port {port} on {computer_id}…",
         lambda: client.publish_port(computer_id, port),
     )
 
-    def render(_: dict[str, Any]) -> None:
+    def render(payload: dict[str, Any]) -> None:
         _UI.console().print(
-            f"[green]✓[/green] public url for [bold]{computer_id}[/bold] pinned to [bold]{port}[/bold]"
+            f"[green]✓[/green] public url for [bold]{computer_id}[/bold] now points at durable app port [bold]{payload.get('published_port') or port}[/bold]"
         )
+        url = payload.get("public_url")
+        if url:
+            _UI.console().print(f"[bold green]→[/bold green] [cyan]{url}[/cyan]")
 
-    return report_success(
-        {
-            "message": f"computer {computer_id} published port {port}",
-            "computer_id": computer_id,
-            "port": port,
-        },
-        render,
-    )
+    return report_success(result, render)
+
+
+def handle_proxy_start(config: RuntimeConfig, computer_id: str | None, specs: list[str] | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if not computer_id:
+        return report_error("computer id is required")
+    if not specs:
+        return report_error("at least one port mapping is required")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    resolved_id = _resolve_computer_ref(client, computer_id)
+    existing_records = _load_proxy_records(clean_stale=True)
+    existing_ports = {int(r.get("local_port") or 0) for r in existing_records}
+    mappings: list[tuple[int, int]] = []
+    seen_ports: set[int] = set()
+    for spec in specs:
+        local_port, remote_port = _parse_proxy_port_spec(spec)
+        if local_port in existing_ports:
+            return report_error(f"local port {local_port} is already in use by a runtime proxy")
+        if local_port in seen_ports:
+            return report_error(f"local port {local_port} was specified more than once")
+        seen_ports.add(local_port)
+        mappings.append((local_port, remote_port))
+
+    started: list[dict[str, Any]] = []
+    started_ports: list[int] = []
+    for local_port, remote_port in mappings:
+        try:
+            _spawn_proxy_agent(config.base_url, str(config.api_key or ""), resolved_id, computer_id, local_port, remote_port)
+        except RuntimeAPIError as exc:
+            if started_ports:
+                _stop_proxy_ports(started_ports, stop_all=False)
+            return report_error(str(exc), status_code=exc.status_code)
+        started_ports.append(local_port)
+        started.append({"computer_id": resolved_id, "computer": computer_id, "local_port": local_port, "remote_port": remote_port})
+
+    def render(payload: dict[str, Any]) -> None:
+        _UI.console().print("[green]✓[/green] proxy started")
+        for proxy in payload.get("proxies", []):
+            _UI.console().print(
+                f"  [bold]localhost:{proxy['local_port']}[/bold] -> [cyan]{proxy['computer']}[/cyan]:{proxy['remote_port']}"
+            )
+
+    return report_success({"proxies": started}, render)
+
+
+def handle_proxy_ls(config: RuntimeConfig) -> int:
+    proxies = _load_proxy_records(clean_stale=True)
+
+    def render(payload: dict[str, Any]) -> None:
+        mods = _UI.rich()
+        Table = mods["Table"]
+        table = Table(title="proxies")
+        table.add_column("VM", style="white")
+        table.add_column("Local", style="cyan")
+        table.add_column("Remote", style="white")
+        table.add_column("Status", style="green")
+        for proxy in payload.get("proxies", []):
+            table.add_row(
+                str(proxy.get("display_name") or proxy.get("computer_id") or "—"),
+                str(proxy.get("local_port") or "—"),
+                str(proxy.get("remote_port") or "—"),
+                str(proxy.get("status") or "unknown"),
+            )
+        _UI.console().print(table)
+
+    return report_success({"proxies": proxies}, render if _interactive() else None)
+
+
+def handle_proxy_stop(config: RuntimeConfig, local_ports: list[int] | None, *, stop_all: bool = False) -> int:
+    if not stop_all and not local_ports:
+        return report_error("pass one or more local ports, or use --all")
+
+    stopped = _stop_proxy_ports(local_ports or [], stop_all=stop_all)
+
+    def render(payload: dict[str, Any]) -> None:
+        _UI.console().print("[green]✓[/green] proxy stopped")
+        for proxy in payload.get("proxies", []):
+            _UI.console().print(
+                f"  [bold]localhost:{proxy.get('local_port')}[/bold] -> [cyan]{proxy.get('display_name') or proxy.get('computer_id')}[/cyan]:{proxy.get('remote_port')}"
+            )
+
+    return report_success({"proxies": stopped}, render if _interactive() else None)
+
+
+def _proxy_preflight(base_url: str, api_key: str, computer_id: str, remote_port: int) -> None:
+    client = RuntimeClient(base_url=base_url, api_key=api_key)
+    ticket_payload = client.create_proxy_ticket(computer_id, remote_port)
+    ws_url = _resolve_ws_url(base_url, ticket_payload.get("ws_url"))
+    if not ws_url:
+        raise RuntimeAPIError("proxy endpoint did not return a websocket url")
+    with websocket_connect(ws_url, open_timeout=DEFAULT_WARMUP_TIMEOUT, close_timeout=1, max_size=None):
+        return
+
+
+
+def run_proxy_agent(base_url: str, api_key: str, computer_id: str, display_name: str, local_port: int, remote_port: int) -> int:
+    if not api_key:
+        print("proxy agent missing api key", file=sys.stderr)
+        return 1
+
+    listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        listener.bind(("127.0.0.1", local_port))
+        listener.listen()
+        listener.settimeout(1.0)
+    except OSError as exc:
+        print(f"proxy listen failed on localhost:{local_port}: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        _proxy_preflight(base_url, api_key, computer_id, remote_port)
+    except Exception as exc:
+        with contextlib.suppress(OSError):
+            listener.close()
+        print(f"proxy preflight failed for localhost:{local_port} -> {computer_id}:{remote_port}: {exc}", file=sys.stderr)
+        return 1
+
+    proxy_dir = _proxy_dir()
+    proxy_dir.mkdir(parents=True, exist_ok=True)
+    state = {
+        "pid": os.getpid(),
+        "computer_id": computer_id,
+        "display_name": display_name,
+        "local_port": local_port,
+        "remote_port": remote_port,
+        "started_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _proxy_state_path(local_port).write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
+
+    stop_event = threading.Event()
+
+    def handle_signal(_signum: int, _frame: Any) -> None:
+        stop_event.set()
+        with contextlib.suppress(OSError):
+            listener.close()
+
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+
+    try:
+        while not stop_event.is_set():
+            try:
+                conn, _ = listener.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                if stop_event.is_set():
+                    break
+                continue
+            thread = threading.Thread(
+                target=_handle_proxy_client,
+                args=(base_url, api_key, computer_id, remote_port, conn),
+                daemon=True,
+            )
+            thread.start()
+    finally:
+        with contextlib.suppress(OSError):
+            listener.close()
+        _remove_proxy_state(local_port)
+    return 0
+
+
+def _handle_proxy_client(base_url: str, api_key: str, computer_id: str, remote_port: int, conn: socket.socket) -> None:
+    client = RuntimeClient(base_url=base_url, api_key=api_key)
+    try:
+        ticket_payload = client.create_proxy_ticket(computer_id, remote_port)
+        ws_url = _resolve_ws_url(base_url, ticket_payload.get("ws_url"))
+        if not ws_url:
+            raise RuntimeAPIError("proxy endpoint did not return a websocket url")
+        with websocket_connect(ws_url, open_timeout=DEFAULT_WARMUP_TIMEOUT, close_timeout=1, max_size=None) as ws:
+            stop = threading.Event()
+
+            def local_to_ws() -> None:
+                try:
+                    while not stop.is_set():
+                        data = conn.recv(65536)
+                        if not data:
+                            break
+                        ws.send(data)
+                except Exception:
+                    pass
+                finally:
+                    stop.set()
+                    with contextlib.suppress(Exception):
+                        ws.close()
+
+            def ws_to_local() -> None:
+                try:
+                    while not stop.is_set():
+                        data = ws.recv()
+                        if data is None:
+                            break
+                        if isinstance(data, str):
+                            chunk = data.encode()
+                        else:
+                            chunk = data
+                        if chunk:
+                            conn.sendall(chunk)
+                except Exception:
+                    pass
+                finally:
+                    stop.set()
+                    with contextlib.suppress(OSError):
+                        conn.shutdown(socket.SHUT_RDWR)
+
+            t1 = threading.Thread(target=local_to_ws, daemon=True)
+            t2 = threading.Thread(target=ws_to_local, daemon=True)
+            t1.start()
+            t2.start()
+            t1.join()
+            t2.join()
+    except Exception as exc:
+        print(f"proxy connection failed for localhost:{conn.getsockname()[1]} -> {computer_id}:{remote_port}: {exc}", file=sys.stderr)
+    finally:
+        with contextlib.suppress(OSError):
+            conn.close()
 
 
 def _enter_computer(config: RuntimeConfig, computer_id: str) -> int:
@@ -1165,7 +1826,7 @@ def _enter_computer(config: RuntimeConfig, computer_id: str) -> int:
         f"preparing console for {computer_id}…",
         lambda: client.create_terminal_ticket(computer_id),
     )
-    ws_url = _resolve_terminal_ws_url(config.base_url, ticket_payload.get("ws_url"))
+    ws_url = _resolve_ws_url(config.base_url, ticket_payload.get("ws_url"))
     if not ws_url:
         return report_error("terminal endpoint did not return a websocket url")
 
@@ -1179,21 +1840,6 @@ def _enter_computer(config: RuntimeConfig, computer_id: str) -> int:
         return report_error(f"terminal failed: {exc}")
 
 
-def _resolve_terminal_ws_url(base_url: str, ws_url: Any) -> str:
-    text = str(ws_url or "").strip()
-    if not text:
-        return ""
-    if text.startswith("ws://") or text.startswith("wss://"):
-        return text
-
-    parsed = urlparse(base_url)
-    scheme = "wss" if parsed.scheme == "https" else "ws"
-    root = f"{scheme}://{parsed.netloc}"
-    if text.startswith("/"):
-        return root + text
-    return urljoin(root + "/", text)
-
-
 def _run_terminal_session(ws_url: str) -> int:
     if not sys.stdin.isatty() or not sys.stdout.isatty():
         return report_error("enter requires an interactive terminal")

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/scripts/runtime_sdk/client.py

@@ -79,6 +79,34 @@ class RuntimeClient:
     def get_computer(self, computer_id: str) -> dict[str, Any]:
         return self._request("GET", f"/api/computers/{computer_id}", auth_required=True)
 
+    def get_computer_network(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/network", auth_required=True)
+
+    def get_startup_config(self, computer_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/computers/{computer_id}/startup", auth_required=True)
+
+    def get_service_config(self, computer_id: str) -> dict[str, Any]:
+        return self.get_startup_config(computer_id)
+
+    def set_startup_config(
+        self,
+        computer_id: str,
+        *,
+        command: str,
+        cwd: str | None = None,
+        port: int,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"command": command, "port": port}
+        if cwd is not None:
+            body["cwd"] = cwd
+        return self._request("PUT", f"/api/computers/{computer_id}/startup", json=body, auth_required=True)
+
+    def clear_startup_config(self, computer_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api/computers/{computer_id}/startup", auth_required=True)
+
+    def clear_service_config(self, computer_id: str) -> dict[str, Any]:
+        return self.clear_startup_config(computer_id)
+
     def start_computer(self, computer_id: str) -> dict[str, Any]:
         return self._request(
             "POST",
@@ -98,6 +126,17 @@ class RuntimeClient:
             timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
         )
 
+    def create_proxy_ticket(self, computer_id: str, port: int) -> dict[str, Any]:
+        if port <= 0 or port > 65535:
+            raise RuntimeAPIError("port must be between 1 and 65535")
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/proxy-ticket",
+            json={"port": port},
+            auth_required=True,
+            timeout=max(self.timeout, DEFAULT_WARMUP_TIMEOUT),
+        )
+
     def run_command(
         self,
         computer_id: str,
@@ -122,17 +161,12 @@ class RuntimeClient:
     def publish_port(self, computer_id: str, port: int) -> dict[str, Any]:
         if port <= 0 or port > 65535:
             raise RuntimeAPIError("port must be between 1 and 65535")
-
-        result = self.run_command(
-            computer_id,
-            f"install -d -m 0755 /run/runtime && printf '%s\\n' '{port}' > /run/runtime/published-port",
-            uid=0,
-            gid=0,
+        return self._request(
+            "POST",
+            f"/api/computers/{computer_id}/publish",
+            json={"port": port},
+            auth_required=True,
         )
-        if result.get("exit_code") != 0:
-            message = result.get("stderr") or result.get("stdout") or "failed to publish port"
-            raise RuntimeAPIError(str(message).strip())
-        return result
 
     def _request(
         self,

{runtime_sdk-0.4.9 → runtime_sdk-0.4.11}/scripts/runtime_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-sdk
-Version: 0.4.9
+Version: 0.4.11
 Summary: Runtime Python SDK and CLI
 Project-URL: Repository, https://github.com/The-Money-Company-Limited/runtimevm
 Project-URL: Issues, https://github.com/The-Money-Company-Limited/runtimevm/issues
@@ -54,16 +54,27 @@ runtime logout
 runtime login --api-key rt_live_...
 
 # Computers
-runtime create                       # in a real TTY, creates then drops you into the console
+runtime create                       # creates a computer with the starter app already published
 runtime create myapp --command "python3 app.py" --cwd /home/ubuntu --port 3000
 runtime enter <name-or-id>         # accepts slug/name like test, or the computer id
 runtime list
 runtime info <id>
 runtime start <id>
-runtime run <id> "echo hello"
+runtime run <id> "echo hello"      # one-shot foreground command only
 runtime run <id> "apt install -y nodejs" --uid 0
-runtime publish <id> 3000
+runtime startup show <id>
+runtime startup set <id> --command "python3 app.py" --cwd /home/ubuntu --port 3000
+runtime startup clear <id>          # low-level durable service config
+runtime service show <id>           # user-facing alias for the durable published app
+runtime service clear <id>
+runtime publish <id> 3000           # promote the running app on port 3000 to the public durable app
 runtime delete <id>
+
+# Inside a running computer, the helper installed by Runtime can manage the
+# durable app without leaving the sandbox:
+#   runtime-env publish 3000
+#   runtime-env service show
+#   runtime-env service clear
 ```
 
 ## Python
@@ -73,12 +84,12 @@ from runtime_sdk import RuntimeClient
 
 client = RuntimeClient(base_url="https://api.runruntime.dev", api_key="rt_live_...")
 
-# Create a computer
+# Create a computer. New computers start with the starter app already published.
 computer = client.create_computer()
 print(computer["public_url"])  # https://goldbird.runruntime.dev
 
-# Or create one with a durable startup command.
-# That startup config is replayed after cold restore / auto-wake.
+# Or create one with an explicit durable app command.
+# That saved service is replayed after cold restore / start.
 app = client.create_computer(
     slug="myapp",
     command="python3 app.py",
@@ -93,7 +104,8 @@ print(result["stdout"])
 # Wake a cold computer explicitly
 client.start_computer(app["id"])
 
-# Pin the public URL to a local app port
+# Promote the running app on a local port to the durable public app.
+# Runtime inspects the listening process and saves its command + cwd when possible.
 client.publish_port(computer["id"], 3000)
 
 # List, info, delete
@@ -120,10 +132,16 @@ make smoke
 Use `make deploy` instead of `make sync` when migrations, env
 files, Caddy, or systemd units changed.
 
-Cold restore and public auto-wake replay the saved startup command only for
-computers created with `--command` + `--port` (or the SDK `command`/`port`
-arguments). If you start an app later via a one-off `runtime run`, the
-filesystem is restored after going cold, but that ad-hoc process is not.
+Cold restore and explicit `runtime start` replay the saved published app command.
+New computers seed that durable app from the starter workspace. Later,
+`runtime publish <id> <port>` can promote a running listener into the saved
+public app definition by inspecting the live process. Inside a running computer,
+`runtime-env publish <port>` does the same thing using a computer-scoped token
+installed by Runtime. `runtime service show|clear` and `runtime-env service
+show|clear` expose that same durable app state directly. The low-level
+`runtime startup ...` commands still map to the same durable state. A one-off
+`runtime run` stays one-shot: the filesystem is restored after going cold, but
+that ad-hoc process is not.
 
 Run the SDK unit tests through the backend project environment: