opensandbox-cli 0.1.0.dev1__py3-none-any.whl

opensandbox_cli/skills/opensandbox-troubleshoot.md

@@ -0,0 +1,112 @@
+---
+name: troubleshoot-sandbox
+description: Troubleshoot OpenSandbox issues by running diagnostics (logs, inspect, events, summary) via CLI or HTTP API to diagnose sandbox failures like OOM, crash, image pull errors, network problems, etc.
+user-invocable: true
+argument-hint: "[sandbox-id]"
+---
+
+# OpenSandbox Troubleshooting
+
+Troubleshoot sandbox $ARGUMENTS using the opensandbox diagnostics.
+
+There are two ways to interact with the diagnostics API: **CLI** (if opensandbox CLI is installed) or **HTTP** (curl against the server directly). Use whichever is available. The HTTP approach works regardless of how the sandbox was created (SDK, API, CLI).
+
+## Workflow
+
+### Step 1: Confirm sandbox state
+
+**CLI:**
+```bash
+opensandbox sandbox get <sandbox-id>
+```
+
+**HTTP:**
+```bash
+curl http://<server-domain>/v1/sandboxes/<sandbox-id>
+```
+
+If the server requires authentication, add `-H "OPEN-SANDBOX-API-KEY: <your-key>"` to all curl commands.
+
+Check the sandbox status (Running, Pending, Paused, Failed, etc.). If the sandbox is not found, it may have been deleted or expired.
+
+### Step 2: Get diagnostics summary (recommended first action)
+
+**CLI:**
+```bash
+opensandbox devops summary <sandbox-id>
+```
+
+**HTTP:**
+```bash
+curl http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/summary
+```
+
+This returns a combined plain-text view of:
+- **Inspect**: container/pod details (status, resources, network, labels)
+- **Events**: state transitions, OOM kills, errors
+- **Logs**: recent container output
+
+Read the output carefully and look for common failure patterns listed below.
+
+### Step 3: Drill down if needed
+
+If the summary is not enough, use individual endpoints for more detail:
+
+**CLI:**
+```bash
+opensandbox devops logs <sandbox-id> --tail 500
+opensandbox devops logs <sandbox-id> --since 30m
+opensandbox devops inspect <sandbox-id>
+opensandbox devops events <sandbox-id> --limit 100
+```
+
+**HTTP:**
+```bash
+# Get more log lines
+curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/logs?tail=500"
+
+# Get logs from recent time window
+curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/logs?since=30m"
+
+# Detailed container/pod inspection
+curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/inspect"
+
+# More events
+curl "http://<server-domain>/v1/sandboxes/<sandbox-id>/diagnostics/events?limit=100"
+```
+
+### Step 4: Diagnose common problems
+
+| Symptom | What to check | Likely cause |
+|---------|---------------|--------------|
+| Status=Pending, no IP | inspect - look for Waiting containers | Image pull failure, insufficient resources, node scheduling |
+| OOMKilled=true | inspect - check memory limits | Container exceeded memory limit, increase memory resource |
+| Exit Code 137 | events + logs | OOM kill or external SIGKILL |
+| Exit Code 1 | logs - check application output | Application error, check entrypoint and env vars |
+| Exit Code 126/127 | logs | Entrypoint command not found or not executable |
+| Connection refused to sandbox | inspect - check ports and network | Service not started inside sandbox, wrong port, network policy blocking |
+| Sandbox stuck in Running but unresponsive | logs (tail=200) | Application hung, check for deadlocks or resource exhaustion |
+| execd health check failing | logs - look for execd errors | execd daemon crashed or port conflict |
+| ImagePullBackOff (K8s) | events | Wrong image name, missing registry credentials |
+| CrashLoopBackOff (K8s) | events + logs | Application keeps crashing, check exit code and logs |
+
+### Step 5: Suggest resolution
+
+Based on the diagnosis, suggest one of:
+- **Image issue**: Verify image name, check registry access
+- **OOM**: Increase memory limit in sandbox creation (e.g. `memory=4Gi`)
+- **Application error**: Fix the entrypoint or application code
+- **Network**: Check network policy, verify port configuration
+- **Scheduling (K8s)**: Check node resources, check pool availability
+- **execd**: Update execd image version, check port conflicts
+
+## API Reference
+
+All diagnostics endpoints return `text/plain` and are available at:
+
+| Endpoint | Query Params | Description |
+|----------|-------------|-------------|
+| `GET /v1/sandboxes/{id}/diagnostics/summary` | `tail` (default 50), `event_limit` (default 20) | Combined inspect + events + logs |
+| `GET /v1/sandboxes/{id}/diagnostics/logs` | `tail` (default 100), `since` (e.g. 10m, 1h) | Container/pod logs |
+| `GET /v1/sandboxes/{id}/diagnostics/inspect` | - | Container/pod detailed state |
+| `GET /v1/sandboxes/{id}/diagnostics/events` | `limit` (default 50) | Container/pod events |

opensandbox_cli/utils.py

@@ -0,0 +1,145 @@
+# Copyright 2026 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared CLI utilities: duration parsing, error handling, key-value parsing."""
+
+from __future__ import annotations
+
+import functools
+import re
+import sys
+from datetime import timedelta
+
+import click
+
+# ---------------------------------------------------------------------------
+# Duration parsing  (e.g. "10m", "1h30m", "90s", "2h")
+# ---------------------------------------------------------------------------
+
+_DURATION_RE = re.compile(
+    r"^(?:(?P<hours>\d+)h)?(?:(?P<minutes>\d+)m)?(?:(?P<seconds>\d+)s)?$"
+)
+
+
+def parse_duration(value: str) -> timedelta:
+    """Parse a human-friendly duration string into a ``timedelta``.
+
+    Supported formats: ``10m``, ``1h30m``, ``90s``, ``2h``, ``1h30m45s``.
+    A plain integer is treated as seconds.
+    """
+    value = value.strip()
+    if not value:
+        raise click.BadParameter("Duration cannot be empty")
+
+    # Plain integer → seconds
+    if value.isdigit():
+        return timedelta(seconds=int(value))
+
+    m = _DURATION_RE.match(value)
+    if not m or not m.group(0):
+        raise click.BadParameter(
+            f"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s."
+        )
+
+    hours = int(m.group("hours") or 0)
+    minutes = int(m.group("minutes") or 0)
+    seconds = int(m.group("seconds") or 0)
+    return timedelta(hours=hours, minutes=minutes, seconds=seconds)
+
+
+class DurationType(click.ParamType):
+    """Click parameter type for duration strings."""
+
+    name = "duration"
+
+    def convert(
+        self, value: str, param: click.Parameter | None, ctx: click.Context | None
+    ) -> timedelta:
+        if isinstance(value, timedelta):
+            return value
+        try:
+            return parse_duration(value)
+        except click.BadParameter:
+            self.fail(
+                f"Invalid duration '{value}'. Use format like 10m, 1h30m, 90s.",
+                param,
+                ctx,
+            )
+
+
+DURATION = DurationType()
+
+
+# ---------------------------------------------------------------------------
+# Key=Value parsing  (e.g. --env FOO=bar)
+# ---------------------------------------------------------------------------
+
+
+class KeyValueType(click.ParamType):
+    """Click parameter type that parses ``KEY=VALUE`` strings into a tuple."""
+
+    name = "KEY=VALUE"
+
+    def convert(
+        self, value: str, param: click.Parameter | None, ctx: click.Context | None
+    ) -> tuple[str, str]:
+        if isinstance(value, tuple):
+            return value
+        if "=" not in value:
+            self.fail(f"Expected KEY=VALUE format, got '{value}'", param, ctx)
+        key, _, val = value.partition("=")
+        return (key, val)
+
+
+KEY_VALUE = KeyValueType()
+
+
+# ---------------------------------------------------------------------------
+# Error handling decorator
+# ---------------------------------------------------------------------------
+
+
+def handle_errors(fn):  # type: ignore[no-untyped-def]
+    """Decorator that catches SDK / HTTP exceptions and prints a friendly message."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]
+        try:
+            return fn(*args, **kwargs)
+        except click.exceptions.Exit:
+            raise
+        except click.ClickException:
+            raise
+        except Exception as exc:
+            # Import here to avoid circular imports at module level
+            from opensandbox.exceptions import SandboxException
+
+            # Try to get the OutputFormatter from the Click context
+            ctx = click.get_current_context(silent=True)
+            obj = getattr(ctx, "obj", None) if ctx else None
+            output = getattr(obj, "output", None) if obj else None
+
+            if output and hasattr(output, "error_panel"):
+                if isinstance(exc, SandboxException):
+                    output.error_panel(str(exc), title="Sandbox Error")
+                else:
+                    output.error_panel(
+                        f"{str(exc)}\n\n[dim]Type: {type(exc).__qualname__}[/]",
+                        title=type(exc).__name__,
+                    )
+            else:
+                click.secho(f"Error: {exc}", fg="red", err=True)
+            sys.exit(1)
+
+    return wrapper