How Does an Agent Know a Service in a Sandbox Is Ready?

# wait_for_url URL [TIMEOUT_SECONDS]
# Returns 0 once the app itself answers (any status), 1 on timeout,
# 2 on a Sandboxer 401 (bad token), 3 if the sandbox is stopped.
wait_for_url() {
  local url=$1 timeout=${2:-120} jar body code title start
  jar=$(mktemp) body=$(mktemp) start=$(date +%s%N)
  while (( ($(date +%s%N) - start) / 1000000000 < timeout )); do
    code=$(curl -sL -b "$jar" -c "$jar" -o "$body" --max-time 10 \
      -w '%{http_code}' "$url") || code=000
    title=""
    if grep -q 'Sandboxer · HTTP' "$body"; then  # a page from the proxy, not the app
      title=$(sed -n 's:.*<title>\(.*\)</title>.*:\1:p' "$body")
      case "$code $title" in
        "401 "*) echo "401 $title" >&2; rm -f "$jar" "$body"; return 2 ;;
        "503 Sandbox is not running") echo "stopped: resume it" >&2; rm -f "$jar" "$body"; return 3 ;;
      esac            # 404 route not live yet, 502 nothing listening, 503 waking: retry
    elif [[ $code != 000 ]]; then
      echo "ready in $(( ($(date +%s%N) - start) / 1000000 )) ms (HTTP $code)"
      rm -f "$jar" "$body"; return 0
    fi
    echo "  $(( ($(date +%s%N) - start) / 1000000 )) ms: $code $title" >&2
    sleep 1
  done
  echo "timed out after ${timeout}s (last: $code $title)" >&2
  rm -f "$jar" "$body"; return 1
}

wait_for_url "https://alert-fluent-lemon-3000.box.sandboxer.com?_token=<token>" 120

  331 ms: 502 Nothing is answering
  1664 ms: 502 Nothing is answering
  3003 ms: 502 Nothing is answering
  4342 ms: 502 Nothing is answering
ready in 6007 ms (HTTP 200)

import http.cookiejar, re, sys, time, urllib.error, urllib.request

def wait_for_url(url: str, timeout: float = 120.0) -> tuple[float, int]:
    """Block until the app behind a hosted URL answers. Returns (seconds waited, status)."""
    opener = urllib.request.build_opener(
        urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
    start = time.monotonic()
    last = None
    while time.monotonic() - start < timeout:
        try:
            with opener.open(url, timeout=10) as r:   # follows the 302 that sets the cookie
                return time.monotonic() - start, r.status
        except urllib.error.HTTPError as e:
            body = e.read().decode("utf-8", "replace")
            if "Sandboxer · HTTP" not in body:         # the app's own 4xx/5xx: it is up
                return time.monotonic() - start, e.code
            title = re.search(r"<title>(.*?)</title>", body).group(1)
            if e.code == 401 or title == "Sandbox is not running":
                raise RuntimeError(f"{e.code} {title}") from None
            last = f"{e.code} {title}"                 # 404 / 502 / 503 waking: retry
        except (urllib.error.URLError, TimeoutError) as e:
            last = str(e)
        time.sleep(1)
    raise TimeoutError(f"not ready after {timeout}s (last: {last})")

if __name__ == "__main__":
    secs, status = wait_for_url(sys.argv[1])
    print(f"ready in {secs:.1f} s (HTTP {status})")

$ python3 wait_for_url.py "https://alert-fluent-lemon-3000.box.sandboxer.com?_token=<token>"
ready in 0.6 s (HTTP 200)
$ python3 wait_for_url.py "https://alert-fluent-lemon-3000.box.sandboxer.com/"
RuntimeError: 401 Access token required