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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-sdk
-Version: 0.4.10
+Version: 0.4.12
 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
@@ -52,18 +52,32 @@ runtime verify 123456
 runtime whoami
 runtime logout
 runtime login --api-key rt_live_...
+runtime api-keys list
+runtime api-keys create "my laptop"
+runtime api-keys revoke 123
 
 # 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 +87,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 +107,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 +135,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.12}/README.md

@@ -33,18 +33,32 @@ runtime verify 123456
 runtime whoami
 runtime logout
 runtime login --api-key rt_live_...
+runtime api-keys list
+runtime api-keys create "my laptop"
+runtime api-keys revoke 123
 
 # 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 +68,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 +88,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 +116,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.12}/pyproject.toml

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

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

@@ -165,16 +165,24 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("whoami")
     subparsers.add_parser("logout")
 
-    create_cmd = subparsers.add_parser("create", help="Create a new computer")
+    api_keys_cmd = subparsers.add_parser("api-keys", help="Manage Runtime API keys")
+    api_keys_subparsers = api_keys_cmd.add_subparsers(dest="api_keys_action", required=True)
+    api_keys_subparsers.add_parser("list", aliases=["ls"], help="List API keys")
+    api_keys_create = api_keys_subparsers.add_parser("create", help="Create a new API key")
+    api_keys_create.add_argument("label", nargs="?", default=None, help="Human-friendly label for the new API key")
+    api_keys_revoke = api_keys_subparsers.add_parser("revoke", help="Revoke an API key")
+    api_keys_revoke.add_argument("id", nargs="?", default=None, help="API key id")
+
+    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 +200,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 +215,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")
@@ -261,6 +288,14 @@ def main(argv: list[str] | None = None) -> int:
             return handle_whoami(config)
         if args.command == "logout":
             return handle_logout(config)
+        if args.command == "api-keys":
+            if args.api_keys_action in ("list", "ls"):
+                return handle_api_keys_list(config)
+            if args.api_keys_action == "create":
+                return handle_api_keys_create(config, args.label)
+            if args.api_keys_action == "revoke":
+                return handle_api_keys_revoke(config, args.id)
+            return report_error("unknown api-keys command")
         if args.command == "create":
             return handle_create(
                 config,
@@ -287,6 +322,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)
@@ -510,7 +559,7 @@ def _spawn_proxy_agent(base_url: str, api_key: str, computer_id: str, display_na
     finally:
         log_file.close()
 
-    deadline = time.time() + 4.0
+    deadline = time.time() + max(4.0, DEFAULT_WARMUP_TIMEOUT + 2.0)
     state_path = _proxy_state_path(local_port)
     while time.time() < deadline:
         if state_path.exists():
@@ -664,7 +713,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")
 
 
 
@@ -682,8 +731,8 @@ def _computer_url_label(c: dict[str, Any]) -> str:
 
 
 
-def _computer_created_label(c: dict[str, Any]) -> str:
-    raw = str(c.get("created_at") or "").strip()
+def _relative_time_label(value: Any) -> str:
+    raw = str(value or "").strip()
     if not raw:
         return ""
     try:
@@ -705,6 +754,11 @@ def _computer_created_label(c: dict[str, Any]) -> str:
 
 
 
+def _computer_created_label(c: dict[str, Any]) -> str:
+    return _relative_time_label(c.get("created_at"))
+
+
+
 def _computer_status_style(status: str) -> str:
     if "cold" in status:
         return "bold cyan"
@@ -999,6 +1053,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"]
@@ -1018,6 +1093,84 @@ def _render_whoami_panel(payload: dict[str, Any]) -> None:
     _UI.console().print(Panel(body, title="whoami", border_style="cyan", expand=False))
 
 
+
+def _api_key_status_label(key: dict[str, Any]) -> str:
+    if key.get("revoked_at"):
+        return "revoked"
+    if key.get("last_used_at"):
+        return "used"
+    return "unused"
+
+
+
+def _api_key_status_style(status: str) -> str:
+    if status == "revoked":
+        return "bold red"
+    if status == "used":
+        return "bold green"
+    return "yellow"
+
+
+
+def _render_api_keys_table(payload: dict[str, Any]) -> None:
+    mods = _UI.rich()
+    Table = mods["Table"]
+    api_keys = payload.get("api_keys") or []
+    if not isinstance(api_keys, list) or not api_keys:
+        _UI.console().print("[yellow]no api keys found[/yellow]")
+        return
+
+    table = Table(title="API keys", expand=True, box=mods["box"].SIMPLE_HEAVY)
+    table.add_column("ID", style="dim", no_wrap=True)
+    table.add_column("Label", style="bold white")
+    table.add_column("Prefix", style="white", no_wrap=True)
+    table.add_column("Created", style="dim", no_wrap=True, justify="right")
+    table.add_column("Last used", style="dim", no_wrap=True, justify="right")
+    table.add_column("Status", no_wrap=True)
+
+    for entry in api_keys:
+        if not isinstance(entry, dict):
+            continue
+        status = _api_key_status_label(entry)
+        style = _api_key_status_style(status)
+        table.add_row(
+            str(entry.get("id") or "—"),
+            str(entry.get("label") or "—"),
+            str(entry.get("key_prefix") or "—"),
+            _relative_time_label(entry.get("created_at")) or "—",
+            _relative_time_label(entry.get("last_used_at")) or "—",
+            f"[{style}]{status}[/{style}]",
+        )
+
+    _UI.console().print(table)
+
+
+
+def _render_api_key_created(payload: dict[str, Any]) -> None:
+    mods = _UI.rich()
+    Panel, Text = mods["Panel"], mods["Text"]
+    key = payload.get("key") or {}
+    secret = str(payload.get("api_key") or "")
+    body = Text()
+    rows = [
+        ("id", key.get("id")),
+        ("label", key.get("label")),
+        ("prefix", key.get("key_prefix")),
+    ]
+    for label, value in rows:
+        if value is None:
+            continue
+        body.append(f"{label:<12}", style="dim")
+        body.append(f"{value}\n")
+    if secret:
+        body.append("save now     ", style="bold yellow")
+        body.append("this secret is only shown once\n", style="yellow")
+        body.append("api key      ", style="dim")
+        body.append(secret, style="bold white")
+        body.append("\n")
+    _UI.console().print(Panel(body, title="api key created", border_style="cyan", expand=False))
+
+
 # --------------------------------------------------------------------------- #
 # Command handlers                                                            #
 # --------------------------------------------------------------------------- #
@@ -1166,6 +1319,56 @@ def handle_logout(config: RuntimeConfig) -> int:
     return report_success({"message": message}, render)
 
 
+
+def handle_api_keys_list(config: RuntimeConfig) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    return report_success(client.list_api_keys(), _render_api_keys_table)
+
+
+
+def handle_api_keys_create(config: RuntimeConfig, label: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if label is None:
+        if not _interactive():
+            return report_error("label is required")
+        label = _prompt_text("API key label")
+        if not label:
+            return report_error("label is required")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    result = client.create_api_key(label)
+    return report_success(result, _render_api_key_created)
+
+
+
+def handle_api_keys_revoke(config: RuntimeConfig, key_id: str | None) -> int:
+    if (err := _require_api_key(config)) is not None:
+        return err
+    if key_id is None:
+        if not _interactive():
+            return report_error("api key id is required")
+        key_id = _prompt_text("API key id")
+        if not key_id:
+            return report_error("api key id is required")
+
+    try:
+        resolved_key_id = int(str(key_id).strip())
+    except ValueError:
+        return report_error("api key id must be a number")
+
+    client = RuntimeClient(base_url=config.base_url, api_key=config.api_key)
+    client.revoke_api_key(resolved_key_id)
+
+    def render(_: dict[str, Any]) -> None:
+        _UI.console().print(f"[green]✓[/green] api key {resolved_key_id} revoked")
+
+    return report_success({"id": resolved_key_id, "message": f"api key {resolved_key_id} revoked"}, render)
+
+
+
 def handle_create(
     config: RuntimeConfig,
     name: str | None,
@@ -1260,6 +1463,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 +1741,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:
@@ -1474,6 +1782,10 @@ def handle_proxy_start(config: RuntimeConfig, computer_id: str | None, specs: li
             if started_ports:
                 _stop_proxy_ports(started_ports, stop_all=False)
             return report_error(str(exc), status_code=exc.status_code)
+        except Exception as exc:
+            if started_ports:
+                _stop_proxy_ports(started_ports, stop_all=False)
+            return report_error(str(exc))
         started_ports.append(local_port)
         started.append({"computer_id": resolved_id, "computer": computer_id, "local_port": local_port, "remote_port": remote_port})
 
@@ -1526,6 +1838,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 +1864,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.12}/scripts/runtime_sdk/client.py

@@ -43,6 +43,15 @@ class RuntimeClient:
     def logout(self) -> dict[str, Any]:
         return self._request("POST", "/api/auth/logout", auth_required=True)
 
+    def list_api_keys(self) -> dict[str, Any]:
+        return self._request("GET", "/api/api-keys", auth_required=True)
+
+    def create_api_key(self, label: str) -> dict[str, Any]:
+        return self._request("POST", "/api/api-keys", json={"label": label}, auth_required=True)
+
+    def revoke_api_key(self, key_id: int) -> dict[str, Any]:
+        return self._request("POST", f"/api/api-keys/{key_id}/revoke", auth_required=True)
+
     # --- Computers ---
 
     def create_computer(
@@ -82,6 +91,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.12}/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.12
 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
@@ -52,18 +52,32 @@ runtime verify 123456
 runtime whoami
 runtime logout
 runtime login --api-key rt_live_...
+runtime api-keys list
+runtime api-keys create "my laptop"
+runtime api-keys revoke 123
 
 # 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 +87,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 +107,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 +135,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: