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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-sdk
-Version: 0.4.10
+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.10 → 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.10 → runtime_sdk-0.4.11}/pyproject.toml

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

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

@@ -165,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")
@@ -192,7 +192,7 @@ def build_parser() -> argparse.ArgumentParser:
     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",
@@ -207,11 +207,30 @@ 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")
@@ -287,6 +306,20 @@ 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)
@@ -664,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")
 
 
 
@@ -999,6 +1032,27 @@ def _render_network_panel(payload: dict[str, Any], *, title: str = "url") -> Non
     _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"]
@@ -1260,6 +1314,111 @@ def handle_url(config: RuntimeConfig, computer_id: str | None) -> int:
     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
@@ -1433,7 +1592,7 @@ def handle_publish(config: RuntimeConfig, computer_id: str | None, port: int | N
 
     def render(payload: dict[str, Any]) -> None:
         _UI.console().print(
-            f"[green]✓[/green] public url for [bold]{computer_id}[/bold] pinned to [bold]{payload.get('published_port') or 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:
@@ -1526,6 +1685,17 @@ def handle_proxy_stop(config: RuntimeConfig, local_ports: list[int] | None, *, s
     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)
@@ -1541,6 +1711,14 @@ def run_proxy_agent(base_url: str, api_key: str, computer_id: str, display_name:
         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 = {

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

@@ -82,6 +82,31 @@ class RuntimeClient:
     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",

{runtime_sdk-0.4.10 → 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.10
+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: