fix: Serve standby Actors at the platform-shaped *.localhost URL

The standbyUrl is now http://<username>--<actor-name>.localhost:3333, where the Actor owns `/` of its
own origin as on *.apify.actor, so an Actor's web UI with root-relative links works. The path form stays
for clients that do not resolve *.localhost, and the Actor object read from an Actor container carries
the http://apify-api:3333/actor-runtime/standby/... form it can reach. Adds sample_actor_standby_web and
e2e tests for an external client and an Actor-to-Actor call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013KAxkpoSLVQvpEJUANjWdp

Author: claude

README.md

@@ -80,11 +80,18 @@ through the API - is served over HTTP at its `standbyUrl`, on the API port:
 ```bash
 cd sample_actor_standby_ts     # or sample_actor_standby_py
 apify push
-curl "http://localhost:3333/actor-runtime/standby/<username>--my-standby-actor-ts/hello?name=Ada&token=<token>"
+curl "http://<username>--my-standby-actor-ts.localhost:3333/hello?name=Ada&token=<token>"
 ```
 
+The `standbyUrl` has the platform's shape, one `*.localhost` hostname per Actor, so a web UI served by the
+Actor works as on `*.apify.actor`. Clients that do not resolve `*.localhost` use
+`http://localhost:3333/actor-runtime/standby/<username>--<actor-name>`, and other Actors
+`http://apify-api:3333/actor-runtime/standby/<username>--<actor-name>`.
+
 The two samples are the same server in TypeScript and Python - JSON endpoints, a request body echo, a
 Server-Sent Events stream, a websocket and stats kept across runs; each README lists the calls.
+`sample_actor_standby_web` serves a web page with root-relative links, and in an ordinary run calls a
+standby Actor from inside its container.
 
 Requests are handed to standby runs the runtime starts, scales by `desiredRequestsPerActorRun` /
 `maxRequestsPerActorRun` and winds down after `idleTimeoutSecs` without a request, as on the platform.

requirements/actor-driver.md

@@ -279,7 +279,8 @@ start`, ...) is refused by name, naming both the `CMD` fix and how to clear debu
 - `ACTOR_STANDBY_PORT` / `ACTOR_WEB_SERVER_PORT` — the port an Actor server listens on, both set to the same
   value (the JavaScript SDK reads the first, the Python SDK the second): a version-level
   `ACTOR_WEB_SERVER_PORT` or `ACTOR_STANDBY_PORT`, else `4321`, as on the platform.
-- `ACTOR_STANDBY_URL` — the Actor's standby URL (`api.md`).
+- `ACTOR_STANDBY_URL` — the Actor's host-facing standby URL, `http://<username>--<actor-name>.localhost:3333`
+  (`api.md`).
 - `APIFY_API_BASE_URL` — the runtime's own API, reachable by name from any
   Actor container on the shared Docker network (see "Networking" above).
 - `APIFY_TOKEN` — the run owner's token

requirements/api.md

@@ -156,11 +156,16 @@
   `null` while Standby is off. `POST` and `PUT /v2/actors` accept `actorStandby`; a partial object is merged
   over the stored settings, over the defaults. An invalid one is `400` `invalid-request`, changing nothing;
   a `tenancy` other than `SINGLE_TENANT` is invalid.
-- The standby URL is `http://localhost:3333/actor-runtime/standby/<username>--<actor-name>`; the Actor id
-  also works in place of `<username>--<actor-name>`. Everything after it - path, query, method, headers,
-  body, websocket upgrades - reaches the Actor's server unchanged, the token included.
-- The platform's host-based shape, `http://<username>--<actor-name>.localhost:3333/<path>`, is served too,
-  for clients that resolve `*.localhost`; its whole path reaches the Actor.
+- The standby URL has the platform's host-based shape, `http://<username>--<actor-name>.localhost:3333`:
+  the Actor owns `/` of its own origin, as on `*.apify.actor`, so a web UI it serves can use root-relative
+  links. Several standby Actors are served side by side, one hostname each.
+- The same Actor is also served at `http://localhost:3333/actor-runtime/standby/<username>--<actor-name>`,
+  for clients that do not resolve `*.localhost`, and at
+  `http://apify-api:3333/actor-runtime/standby/<username>--<actor-name>` from Actor containers. The Actor
+  object read from an Actor container carries this container form as its `standbyUrl`.
+- The Actor id also works in place of `<username>--<actor-name>` in every form. Everything after the
+  standby URL - path, query, method, headers, body, websocket upgrades - reaches the Actor's server
+  unchanged, the token included.
 - Authenticated like the API (`Authorization: Bearer`, `?token=`), plus the platform's
   `x-apify-authorization` header; only the Actor's owner is served.
 - Errors, as `{ "error": { "type", "message" } }`: no token `401` `user-not-authenticated`; no such Actor of

requirements/test.md

@@ -53,3 +53,7 @@ Test case must verify full Actor development flow:
 - Assert that plain, body-carrying, streamed and websocket requests to its standby URL are all answered by
   one `STANDBY` run, that the run ends `SUCCEEDED` once idle with one dataset item per greeting, and that
   the next request starts a new run
+- For `sample_actor_standby_web`: push, then assert that an external client reaches its standby endpoint at
+  the `*.localhost` standby URL, where the Actor's page links to its API root-relative, and by the path
+  form; and that an ordinary run of an Actor calls the standby endpoint from inside its container, by the
+  `standbyUrl` it reads through the API

sample_actor_standby_web/.actor/actor.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://apify.com/schemas/v1/actor.ide.json",
+	"actorSpecification": 1,
+	"name": "my-standby-web-actor",
+	"title": "Standby web page sample actor for actor-runtime",
+	"description": "In Standby mode, a web page and the JSON endpoint it calls with a root-relative URL. An ordinary run calls a standby Actor's endpoint from inside its container.",
+	"version": "0.0",
+	"buildTag": "latest",
+	"usesStandbyMode": true,
+	"input": "./input_schema.json",
+	"dockerfile": "../Dockerfile"
+}

sample_actor_standby_web/.actor/input_schema.json

@@ -0,0 +1,20 @@
+{
+	"title": "Standby web sample input",
+	"type": "object",
+	"schemaVersion": 1,
+	"properties": {
+		"standbyActor": {
+			"title": "Standby Actor",
+			"type": "string",
+			"description": "The standby Actor an ordinary run calls, as an id or `username/name`. Empty means this Actor itself.",
+			"editor": "textfield"
+		},
+		"name": {
+			"title": "Name",
+			"type": "string",
+			"description": "Sent to the standby Actor's `/api/greeting` endpoint.",
+			"editor": "textfield",
+			"default": "Actor"
+		}
+	}
+}

sample_actor_standby_web/.dockerignore

@@ -0,0 +1,18 @@
+# configurations
+.idea
+.vscode
+.zed
+
+# crawlee and apify storage folders
+apify_storage
+crawlee_storage
+storage
+
+# installed files
+node_modules
+
+# git folder
+.git
+
+# dist folder
+dist

sample_actor_standby_web/Dockerfile

@@ -0,0 +1,20 @@
+FROM apify/actor-node:24 AS builder
+
+COPY --chown=myuser:myuser package*.json ./
+RUN npm install --include=dev --audit=false
+
+COPY --chown=myuser:myuser . ./
+RUN npm run build
+
+FROM apify/actor-node:24
+
+COPY --chown=myuser:myuser package*.json ./
+RUN npm --quiet set progress=false \
+    && npm install --omit=dev --omit=optional --audit=false \
+    && rm -r ~/.npm
+
+COPY --from=builder --chown=myuser:myuser /usr/src/app/dist ./dist
+COPY --chown=myuser:myuser . ./
+
+# The interpreter itself, not `npm start`, so the runtime's debug mode can attach too.
+CMD ["node", "dist/main.js"]

sample_actor_standby_web/README.md

@@ -0,0 +1,24 @@
+# Standby web sample Actor
+
+A small Actor for trying Actor Standby callers against the local runtime. `.actor/actor.json` sets
+`usesStandbyMode`, so `apify push` enables Standby.
+
+- **Standby run**: serves a web page whose script calls `GET /api/greeting` with a root-relative URL, as most
+  web UIs do. That works because the Actor owns `/` of its standby URL, as on `*.apify.actor`.
+- **Ordinary run** (`apify call`): a client of a standby Actor, this one unless the `standbyActor` input
+  names another. It reads that Actor's `standbyUrl` through the API - from inside a container that is
+  `http://apify-api:3333/actor-runtime/standby/<username>--<actor-name>` - calls `/api/greeting` there and
+  pushes the answer to its default dataset.
+
+```bash
+apify push
+TOKEN=<your token>
+
+# In a browser:
+#   http://<username>--my-standby-web-actor.localhost:3333/?token=<your token>
+curl "http://<username>--my-standby-web-actor.localhost:3333/api/greeting?name=Ada&token=$TOKEN"
+# The same endpoint, for clients that do not resolve *.localhost:
+curl "http://localhost:3333/actor-runtime/standby/<username>--my-standby-web-actor/api/greeting?name=Ada&token=$TOKEN"
+
+apify call --input '{"name":"Actor"}'   # another run calls the standby endpoint from its container
+```