@p10i/create-nestbox 0.2.0 → 0.4.0

package/.env.example

@@ -8,9 +8,9 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
-# Absolute host-state directory shared only by the native runner and control.
-# The creator generates this value outside the mounted workspace.
-NESTBOX_HOST_QUEUE_PATH=
+# The native runner uses the shared WEB_PORT gateway. The creator generates a
+# private token file outside the workspace and mounts it only into control.
+NESTBOX_HOST_TOKEN_FILE=
 
 # Override for rootless or nonstandard Docker Engine installations.
 DOCKER_SOCKET_PATH=/var/run/docker.sock

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0
+
+- Route the authenticated host runner through `/_nestbox/host/` on the existing Nginx gateway.
+- Restore the one-Nestbox, one-published-port invariant while keeping the control APIs private.
+
+## 0.3.0
+
+- Replace the filesystem host queue with authenticated HTTP long polling managed by `control`.
+- Publish only the dedicated host-runner endpoint on loopback; keep the container API internal.
+- Remove queue paths, bind mounts, polling files, and stale lock/result state.
+- Generate a per-installation runner token file unavailable to application containers and preserve existing MCP and PHP contracts.
+
 ## 0.2.0
 
 - Add a private, label-gated container control service and OpenCode MCP adapter.

package/INSTALL.md

@@ -12,13 +12,15 @@ npm create @p10i/nestbox@latest
 
 The published npm package is `@p10i/create-nestbox`; npm maps `npm create @p10i/nestbox` to that package. The creator explains and previews one of the two default layouts before writing files. The recommended layout installs at `<workspace>/.nestbox` so Nestbox stays separate from project files. The direct layout writes Nestbox files into an empty selected directory. The creator copies `.env.example` to `.env`, copies `home/configs/opencode/instance.example.md` to `instance.md`, records npm package provenance in the instance policy, and initializes fresh installation Git history when Git is available.
 
-The creator does not start Docker, start the host bridge, or collect secrets. Node.js and npm are required for the bridge. After it finishes, edit `.env`, run `npm run host --` from the workspace in a separate terminal, then run from the installation directory:
+The creator does not start Docker, start the host bridge, or collect secrets. Node.js and npm are required for the bridge. After it finishes, edit `.env`, then run from the installation directory:
 
 ```sh
 docker compose config --quiet
 docker compose up -d --build
 ```
 
+After `control` is healthy, run `npm run host --` from the workspace in a separate terminal.
+
 Then run the host test suite documented in section 7.
 
 ## 1. Choose Language
@@ -42,7 +44,7 @@ Both defaults keep pages, Compose, Dockerfiles, configuration, dependencies, and
 
 Do not present vendoring, a parent-owned engine, a submodule, an external page tree, or another shared-repository arrangement as a default. These are optional adaptations discussed only when the user requests one.
 
-Never overwrite an existing installation. Inspect an existing target and ask whether to update, repair, reuse, or stop.
+Never overwrite an existing installation. Select a different target or stop.
 
 ## 3. Check Requirements And Git
 
@@ -98,9 +100,9 @@ Configure the host bridge in the workspace root before Compose starts:
 
 - For `.nestbox` layout, create `package.json` from `.nestbox/package.host.json` when absent, or merge only its `host` and `test:host` scripts into the existing manifest.
 - For direct layout, use `node host-runner.mjs` and `node tests/host-runner.mjs` for those scripts. A source clone's publisher-oriented `package.json` may be replaced by this installation manifest after preserving any intentional project metadata.
-- Never overwrite a conflicting script. Stop and ask for a different script name or an explicit migration.
-- Create a private host-state queue outside the workspace, record it in the ignored installation `.runtime/host-runner.json`, and set its absolute path as `NESTBOX_HOST_QUEUE_PATH` in `.env`. The npm creator performs this automatically.
-- Start `npm run host --` before Compose so the queue and heartbeat exist. The runner rejects queue locations inside the mounted workspace.
+- Never overwrite a conflicting script. Stop and ask for a different script name.
+- Set `NESTBOX_HOST_TOKEN_FILE` to a private file outside every container-mounted workspace. The npm creator writes a 64-character token there with owner-only permissions. Only `control` mounts the file; never paste the token into chat or expose it through a page.
+- Start `npm run host --` after `control` is healthy. The runner authenticates through `/_nestbox/host/` on the existing `WEB_PORT`, long-polls for work, sends heartbeats, and posts results without opening a host listener, publishing a second port, or sharing queue files.
 - The workspace manifest is mounted read-only in runtime containers. Confirmed changes are written only by the native host runner.
 
 Update the new `home/configs/opencode/instance.md` with:
@@ -271,4 +273,4 @@ When a super-document intentionally changes files in `/workspace`, follow that w
 
 ## 11. Optional Adaptations
 
-Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership and update consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.
+Retaining upstream Git history, adding an upstream remote, external page trees, parent-owned engines, submodules, vendoring, shared repositories, alternate Compose layouts, and operating-system shortcuts are optional. Explain their ownership consequences and obtain explicit confirmation before creating them. They must not obscure the two default installation paths.

package/README.md

@@ -12,7 +12,7 @@ Nestbox runs with Docker Compose using Nginx, PHP-FPM, Rollup, OpenCode, and a p
 
 The `control` service is the only container with `/var/run/docker.sock`. Its internal-only API permits exec only when caller, target, project, and root-user labels allow it. OpenCode reaches the API through the bundled control MCP and can target PHP-FPM and Rollup by default. Trusted PHP pages can use `nestbox_control_exec()` and are restricted to PHP-FPM self-exec.
 
-Native host commands are limited to scripts already declared in the workspace `package.json`. Keep `npm run host --` running from the workspace when host scripts are needed. The bridge exchanges typed files through creator-generated host state outside the container-mounted workspace; it opens no network listener. MCP can request script additions, edits, or deletions, but the host runner applies them only after the user supplies a short-lived code displayed exclusively in the host terminal.
+Native host commands are limited to scripts already declared in the workspace `package.json`. Keep `npm run host --` running from the workspace when host scripts are needed. The native runner authenticates with an external token file mounted only into `control`, long-polls `/_nestbox/host/` through the shared Nginx gateway port, and posts results; no host server, second published port, or shared filesystem queue is used. MCP can request script additions, edits, or deletions, but the host runner applies them only after the user supplies a short-lived code displayed exclusively in the host terminal.
 
 Control emits bounded structured events to ordinary container logs. Use `docker compose logs control`; no telemetry collector, database, or observability dependency is installed. Docker socket access is root-equivalent on the host, and host scripts execute in the trusted writable workspace, so neither mechanism is a sandbox.
 
@@ -39,11 +39,3 @@ For agent-guided installation or repair work, copy and send this to an agent wit
 ```text
 Install Nestbox by following https://github.com/piontkovsk11andre1/nestbox/blob/main/INSTALL.md completely. Ask all required questions before making changes, preserve unrelated files and Git history, and do not expose secrets.
 ```
-
-## Update
-
-Run an update request from the workspace containing Nestbox, then copy and send this prompt to an agent with filesystem, Git, Docker, and terminal access:
-
-```text
-Update this Nestbox installation from https://github.com/piontkovsk11andre1/nestbox. Locate the installation, inspect its local Git history and configuration, read the current remote INSTALL.md and internal Nestbox instructions, preserve pages, instance policy, secrets, volumes, and unrelated changes, explain the proposed update, and ask before destructive or system-level operations. Validate Compose and run the Nestbox host tests after applying the update.
-```

package/bin/create-nestbox.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { cp, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
 
+function containsPath(root, target) {
+  const child = relative(resolve(root), resolve(target));
+  return child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child));
+}
+
 const copyEntries = [
   'docker',
   'home',
@@ -147,7 +152,7 @@ async function configureInstance(installDir, workspaceDir, layout) {
   });
   const envPath = join(installDir, '.env');
   const workspaceValue = layout === 'nestbox' ? '..' : '.';
-  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^WORKSPACE_PATH=.*$/m, `WORKSPACE_PATH=${workspaceValue}`);
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^WORKSPACE_PATH=.*\r?$/m, `WORKSPACE_PATH=${workspaceValue}`);
   await writeFile(envPath, configuredEnv, 'utf8');
 
   const instanceExample = join(installDir, 'home', 'configs', 'opencode', 'instance.example.md');
@@ -222,18 +227,21 @@ async function configureHostPackage(installDir, workspaceDir, layout) {
     private: true,
     scripts
   }, null, 2)}\n`, 'utf8');
+  const envPath = join(installDir, '.env');
+  const token = randomBytes(32).toString('hex');
   const stateBase = process.env.NESTBOX_CREATOR_STATE_ROOT
     || process.env.LOCALAPPDATA
     || process.env.XDG_STATE_HOME
     || (process.platform === 'darwin' ? join(homedir(), 'Library', 'Application Support') : join(homedir(), '.local', 'state'));
-  const queue = join(stateBase, 'nestbox', 'host-runner', randomUUID());
-  await mkdir(queue, { recursive: true });
-  const runtime = join(installDir, '.runtime');
-  await mkdir(runtime, { recursive: true });
-  await writeFile(join(runtime, 'host-runner.json'), `${JSON.stringify({ queue }, null, 2)}\n`, 'utf8');
-  const envPath = join(installDir, '.env');
-  const composeQueue = queue.replaceAll('\\', '/');
-  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_QUEUE_PATH=.*$/m, () => `NESTBOX_HOST_QUEUE_PATH=${composeQueue}`);
+  const tokenDirectory = join(stateBase, 'nestbox', 'host-control');
+  await mkdir(tokenDirectory, { recursive: true });
+  const tokenPath = join(await realpath(tokenDirectory), `${randomUUID()}.token`);
+  const canonicalWorkspace = await realpath(workspaceDir);
+  const canonicalInstall = await realpath(installDir);
+  if (containsPath(canonicalWorkspace, tokenPath) || containsPath(canonicalInstall, tokenPath)) throw new Error('Host token state directory must be outside the workspace and Nestbox installation.');
+  await writeFile(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+  const composeTokenPath = tokenPath.replaceAll('\\', '/');
+  const configuredEnv = (await readFile(envPath, 'utf8')).replace(/^NESTBOX_HOST_TOKEN_FILE=.*\r?$/m, () => `NESTBOX_HOST_TOKEN_FILE=${composeTokenPath}`);
   await writeFile(envPath, configuredEnv, 'utf8');
 }
 
@@ -286,12 +294,13 @@ async function main() {
     console.log(`Workspace: ${workspaceDir}`);
     console.log(`Git initialized: ${gitInitialized ? 'yes' : 'no'}`);
     console.log('\nNext steps:');
-    console.log(`  cd ${workspaceDir}`);
-    console.log('  npm run host --');
     console.log(`  cd ${installDir}`);
     console.log('  Edit .env and set COMPOSE_PROJECT_NAME, WEB_PORT, OpenCode credentials, and provider keys.');
     console.log('  docker compose config --quiet');
     console.log('  docker compose up -d --build');
+    console.log(`  cd ${workspaceDir}`);
+    console.log('  npm run host --');
+    console.log(`  cd ${installDir}`);
     console.log(process.platform === 'win32' ? '  .\\tests\\nestbox.ps1' : '  bash tests/nestbox.sh');
   } finally {
     rl.close();

package/docker/control/server.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import http.client
+import hmac
 import json
 import os
 import re
@@ -10,16 +11,24 @@ import time
 import uuid
 from datetime import datetime, timezone
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from urllib.parse import quote, unquote, urlparse
+from urllib.parse import parse_qs, quote, unquote, urlparse
 
 DOCKER_SOCKET = os.environ.get("DOCKER_SOCKET", "/var/run/docker.sock")
 WORKSPACE_PATH = os.environ.get("WORKSPACE_PATH", "/workspace")
 PROJECT_NAME = os.environ.get("COMPOSE_PROJECT_NAME", "").strip()
 SERVICE_NAME = os.environ.get("NESTBOX_CONTROL_SERVICE", "control")
-HOST_ROOT = os.environ.get("NESTBOX_HOST_RUNNER_PATH", "/host-runner")
+HOST_TOKEN_FILE = os.environ.get("NESTBOX_HOST_TOKEN_FILE", "/run/secrets/nestbox-host-token")
+try:
+    with open(HOST_TOKEN_FILE, encoding="utf-8") as token_stream:
+        HOST_TOKEN = token_stream.read().strip()
+except OSError:
+    HOST_TOKEN = ""
 HOST_TIMEOUT = int(os.environ.get("NESTBOX_HOST_RUNNER_TIMEOUT", "3600"))
-HOST_HEARTBEAT_TTL = int(os.environ.get("NESTBOX_HOST_RUNNER_HEARTBEAT_TTL", "5"))
+HOST_HEARTBEAT_TTL = int(os.environ.get("NESTBOX_HOST_RUNNER_HEARTBEAT_TTL", "10"))
+HOST_LONG_POLL_TIMEOUT = int(os.environ.get("NESTBOX_HOST_LONG_POLL_TIMEOUT", "25"))
+MAX_HOST_JOBS = int(os.environ.get("NESTBOX_MAX_HOST_JOBS", "100"))
 MAX_BODY_BYTES = 128 * 1024
+MAX_HOST_BODY_BYTES = 64 * 1024 * 1024
 MAX_COMMAND_PARTS = 256
 MAX_COMMAND_BYTES = 64 * 1024
 LOG_OUTPUT = os.environ.get("NESTBOX_CONTROL_LOG_OUTPUT", "text").lower()
@@ -191,51 +200,155 @@ def package_scripts():
     return {str(name): str(command) for name, command in scripts.items()}
 
 
-def host_paths():
-    return {name: os.path.join(HOST_ROOT, name) for name in ("requests", "results", "heartbeat")}
+class HostBroker:
+    def __init__(self):
+        self.condition = threading.Condition()
+        self.pending = []
+        self.jobs = {}
+        self.runner = {}
+
+    def touch(self, runner_id, headers):
+        if not re.fullmatch(r"[A-Za-z0-9._:-]{8,128}", runner_id):
+            raise ValueError("invalid runner ID")
+        now = time.monotonic()
+        with self.condition:
+            active_id = self.runner.get("id")
+            active_age = now - self.runner.get("seen", 0)
+            if active_id and active_id != runner_id and active_age <= HOST_HEARTBEAT_TTL:
+                raise PermissionError("another host runner is active")
+            if active_id and active_id != runner_id:
+                for record in self.jobs.values():
+                    if record.get("runnerId") == active_id and record.get("result") is None:
+                        record["result"] = {
+                            "jobId": record["job"]["jobId"],
+                            "exitCode": 1,
+                            "stdout": "",
+                            "stderr": "The assigned host runner disconnected before returning a result.",
+                            "interrupted": True,
+                        }
+            self.runner = {
+                "id": runner_id,
+                "seen": now,
+                "pid": headers.get("X-Nestbox-Runner-Pid"),
+                "platform": headers.get("X-Nestbox-Runner-Platform"),
+                "hostname": headers.get("X-Nestbox-Runner-Host"),
+            }
+            self.condition.notify_all()
+
+    def status(self):
+        with self.condition:
+            if not self.runner:
+                return {"available": False}
+            age = max(0, time.monotonic() - self.runner["seen"])
+            return {
+                "available": age <= HOST_HEARTBEAT_TTL,
+                "ageSeconds": round(age, 3),
+                "pid": self.runner.get("pid"),
+                "platform": self.runner.get("platform"),
+                "hostname": self.runner.get("hostname"),
+            }
+
+    def enqueue(self, job):
+        with self.condition:
+            if len(self.jobs) >= MAX_HOST_JOBS:
+                raise RuntimeError("too many host jobs are pending")
+            self.jobs[job["jobId"]] = {"job": job, "result": None, "runnerId": None}
+            self.pending.append(job["jobId"])
+            self.condition.notify_all()
+
+    def next(self, runner_id, headers, timeout):
+        deadline = time.monotonic() + timeout
+        with self.condition:
+            while True:
+                if self.runner.get("id") != runner_id:
+                    raise PermissionError("another host runner is active")
+                if time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                    return None
+                if self.pending:
+                    identifier = self.pending.pop(0)
+                    record = self.jobs.get(identifier)
+                    if record:
+                        record["runnerId"] = runner_id
+                        return record["job"]
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return None
+                self.condition.wait(min(1, remaining))
+
+    def complete(self, runner_id, identifier, result):
+        with self.condition:
+            record = self.jobs.get(identifier)
+            if not record or record.get("runnerId") != runner_id:
+                raise ValueError("host job is unknown or belongs to another runner")
+            if record.get("result") is not None:
+                raise ValueError("host job already has a result")
+            if result.get("jobId") != identifier:
+                raise ValueError("host result contains a mismatched job ID")
+            job = record["job"]
+            if job["type"] == "npm.run":
+                if not isinstance(result.get("exitCode"), int) or not isinstance(result.get("stdout"), str) or not isinstance(result.get("stderr"), str):
+                    raise ValueError("invalid npm run result")
+            elif job["type"] == "npm.scripts.request":
+                if result.get("status") != "confirmation_required" or result.get("requestId") != job.get("requestId") or result.get("operation") != job.get("operation") or result.get("name") != job.get("name"):
+                    if not isinstance(result.get("exitCode"), int):
+                        raise ValueError("invalid script change request result")
+            elif job["type"] == "npm.scripts.confirm":
+                if result.get("status") == "success" and result.get("requestId") != job.get("requestId"):
+                    raise ValueError("invalid script confirmation result")
+                if result.get("status") != "success" and not isinstance(result.get("exitCode"), int):
+                    raise ValueError("invalid script confirmation result")
+            record["result"] = result
+            self.condition.notify_all()
+
+    def wait(self, identifier, timeout=HOST_TIMEOUT):
+        deadline = time.monotonic() + timeout
+        with self.condition:
+            while True:
+                record = self.jobs.get(identifier)
+                if record and record.get("runnerId") and record.get("result") is None:
+                    owner = record["runnerId"]
+                    if self.runner.get("id") != owner or time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                        record["result"] = {
+                            "jobId": identifier,
+                            "exitCode": 1,
+                            "stdout": "",
+                            "stderr": "The assigned host runner disconnected before returning a result.",
+                            "interrupted": True,
+                        }
+                elif record and record.get("result") is None and self.runner and time.monotonic() - self.runner.get("seen", 0) > HOST_HEARTBEAT_TTL:
+                    record["result"] = {
+                        "jobId": identifier,
+                        "exitCode": 1,
+                        "stdout": "",
+                        "stderr": "The host runner disconnected before accepting the job.",
+                        "interrupted": True,
+                    }
+                if record and record.get("result") is not None:
+                    result = record["result"]
+                    del self.jobs[identifier]
+                    return result
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    self.jobs.pop(identifier, None)
+                    if identifier in self.pending:
+                        self.pending.remove(identifier)
+                    raise TimeoutError(f"host runner did not finish within {timeout} seconds")
+                self.condition.wait(min(1, remaining))
+
+
+HOST_BROKER = HostBroker()
 
 
 def host_status():
-    paths = host_paths()
-    try:
-        age = max(0, time.time() - os.path.getmtime(paths["heartbeat"] + ".json"))
-        with open(paths["heartbeat"] + ".json", encoding="utf-8") as stream:
-            heartbeat = json.load(stream)
-        return {"available": age <= HOST_HEARTBEAT_TTL, "ageSeconds": round(age, 3), "pid": heartbeat.get("pid"), "platform": heartbeat.get("platform"), "hostname": heartbeat.get("hostname")}
-    except (OSError, ValueError, TypeError):
-        return {"available": False}
-
-
-def atomic_json(path, value):
-    temporary = f"{path}.{uuid.uuid4().hex}.tmp"
-    with open(temporary, "w", encoding="utf-8") as stream:
-        json.dump(value, stream, sort_keys=True)
-        stream.write("\n")
-    os.replace(temporary, path)
+    return HOST_BROKER.status()
 
 
 def enqueue(job):
-    paths = host_paths()
-    os.makedirs(paths["requests"], exist_ok=True)
-    os.makedirs(paths["results"], exist_ok=True)
-    atomic_json(os.path.join(paths["requests"], f"{job['jobId']}.json"), job)
-    return paths
+    HOST_BROKER.enqueue(job)
 
 
-def wait_result(identifier, paths, timeout=HOST_TIMEOUT):
-    path = os.path.join(paths["results"], f"{identifier}.json")
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        try:
-            with open(path, encoding="utf-8") as stream:
-                result = json.load(stream)
-            os.unlink(path)
-            if result.get("jobId") != identifier:
-                raise ValueError("host runner returned a mismatched job ID")
-            return result
-        except FileNotFoundError:
-            time.sleep(0.1)
-    raise TimeoutError(f"host runner did not finish within {timeout} seconds")
+def wait_result(identifier, timeout=HOST_TIMEOUT):
+    return HOST_BROKER.wait(identifier, timeout)
 
 
 def record_host_result(identifier, source_name, script, result, detached):
@@ -245,9 +358,9 @@ def record_host_result(identifier, source_name, script, result, detached):
     log_event("npm.complete", runId=identifier, source=source_name, script=script, detached=detached, executor="host", exitCode=result.get("exitCode"), hostPlatform=result.get("hostPlatform"), hostName=result.get("hostName"), stdoutTruncated=bool(result.get("stdoutTruncated")), stderrTruncated=bool(result.get("stderrTruncated")))
 
 
-def wait_detached(identifier, paths, source_name, script):
+def wait_detached(identifier, source_name, script):
     try:
-        record_host_result(identifier, source_name, script, wait_result(identifier, paths), True)
+        record_host_result(identifier, source_name, script, wait_result(identifier), True)
     except Exception as error:
         log_event("npm.error", runId=identifier, source=source_name, script=script, detached=True, error=str(error))
 
@@ -259,7 +372,7 @@ def valid_command(command):
 
 
 class Handler(BaseHTTPRequestHandler):
-    server_version = "nestbox-control/0.2"
+    server_version = "nestbox-control/0.4"
 
     def setup(self):
         super().setup()
@@ -398,11 +511,11 @@ class Handler(BaseHTTPRequestHandler):
         identifier = run_id("npm")
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.run", "script": script, "args": args, "source": service(source), "createdAt": now_iso()}
         try:
-            paths = enqueue(job)
+            enqueue(job)
             if body.get("detach"):
-                threading.Thread(target=wait_detached, args=(identifier, paths, service(source), script), daemon=True).start()
+                threading.Thread(target=wait_detached, args=(identifier, service(source), script), daemon=True).start()
                 self.send_json(202, {"runId": identifier, "detached": True, "executor": "host"}); return
-            result = wait_result(identifier, paths)
+            result = wait_result(identifier)
             record_host_result(identifier, service(source), script, result, False)
             self.send_json(200, {"runId": identifier, "exitCode": result.get("exitCode"), "stdout": str(result.get("stdout", "")), "stderr": str(result.get("stderr", "")), "pid": result.get("pid"), "executor": "host"})
         except Exception as error:
@@ -422,7 +535,8 @@ class Handler(BaseHTTPRequestHandler):
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.scripts.request", "requestId": identifier, "operation": operation, "name": name, "source": service(source), "createdAt": now_iso()}
         if operation != "delete": job["command"] = command
         try:
-            result = wait_result(identifier, enqueue(job))
+            enqueue(job)
+            result = wait_result(identifier)
             if result.get("status") != "confirmation_required": raise ValueError(result.get("stderr", "host runner rejected the request"))
             self.send_json(202, {"status": "confirmation_required", "requestId": result.get("requestId"), "operation": operation, "name": name, "expiresAt": result.get("expiresAt")})
         except Exception as error:
@@ -437,16 +551,108 @@ class Handler(BaseHTTPRequestHandler):
         identifier = run_id("npm-script-confirm")
         job = {"schemaVersion": 1, "jobId": identifier, "type": "npm.scripts.confirm", "requestId": request_id, "code": code, "source": service(source), "createdAt": now_iso()}
         try:
-            result = wait_result(identifier, enqueue(job))
+            enqueue(job)
+            result = wait_result(identifier)
             if result.get("status") != "success": raise ValueError(result.get("stderr", "host runner rejected the confirmation"))
             self.send_json(200, {"status": "success", "requestId": request_id, "operation": result.get("operation"), "name": result.get("name")})
         except Exception as error:
             self.send_json(400, {"error": str(error)})
 
 
+class HostHandler(BaseHTTPRequestHandler):
+    server_version = "nestbox-host-control/0.4"
+
+    def setup(self):
+        super().setup()
+        self.connection.settimeout(HOST_LONG_POLL_TIMEOUT + 10)
+
+    def log_message(self, fmt, *args):
+        log_event("host.http.access", client=self.address_string(), message=fmt % args)
+
+    def send_json(self, status, value):
+        payload = json.dumps(value, ensure_ascii=False).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def authorized(self):
+        supplied = self.headers.get("Authorization", "")
+        expected = f"Bearer {HOST_TOKEN}"
+        return hmac.compare_digest(supplied.encode(), expected.encode())
+
+    def runner(self):
+        return self.headers.get("X-Nestbox-Runner-Id", "")
+
+    def body(self):
+        if self.headers.get("Transfer-Encoding"):
+            raise ValueError("transfer encoding is not supported")
+        length = int(self.headers.get("Content-Length", "0"))
+        if length < 0 or length > MAX_HOST_BODY_BYTES:
+            raise ValueError("request body is too large")
+        value = json.loads(self.rfile.read(length)) if length else {}
+        if not isinstance(value, dict):
+            raise ValueError("request body must be a JSON object")
+        return value
+
+    def authenticate(self):
+        if not self.authorized():
+            self.send_json(401, {"error": "invalid host runner token"})
+            return False
+        try:
+            HOST_BROKER.touch(self.runner(), self.headers)
+            return True
+        except PermissionError as error:
+            self.send_json(409, {"error": str(error)})
+        except ValueError as error:
+            self.send_json(400, {"error": str(error)})
+        return False
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        if parsed.path == "/host/health":
+            if not self.authenticate(): return
+            self.send_json(200, {"ok": True, "hostRunner": host_status()})
+            return
+        if parsed.path == "/host/jobs/next":
+            if not self.authenticate(): return
+            try:
+                requested = int((parse_qs(parsed.query).get("timeout") or [HOST_LONG_POLL_TIMEOUT])[0])
+                timeout = max(1, min(HOST_LONG_POLL_TIMEOUT, requested))
+                job = HOST_BROKER.next(self.runner(), self.headers, timeout)
+                if job is None:
+                    self.send_response(204); self.end_headers(); return
+                self.send_json(200, job)
+            except (TypeError, ValueError) as error:
+                self.send_json(400, {"error": str(error)})
+            return
+        self.send_json(404, {"error": "not found"})
+
+    def do_POST(self):
+        if not self.authenticate(): return
+        path = urlparse(self.path).path
+        if path == "/host/heartbeat":
+            self.send_json(200, {"ok": True})
+            return
+        match = re.fullmatch(r"/host/jobs/([A-Za-z0-9._:-]{1,128})/result", path)
+        if not match:
+            self.send_json(404, {"error": "not found"}); return
+        try:
+            result = self.body()
+            HOST_BROKER.complete(self.runner(), match.group(1), result)
+            self.send_json(202, {"accepted": True})
+        except ValueError as error:
+            self.send_json(400, {"error": str(error)})
+
+
 def main():
     if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", PROJECT_NAME):
         raise SystemExit("COMPOSE_PROJECT_NAME must be a non-empty lowercase project slug")
+    if len(HOST_TOKEN) < 32:
+        raise SystemExit("NESTBOX_HOST_TOKEN_FILE must contain a token of at least 32 characters")
+    host_server = ThreadingHTTPServer(("0.0.0.0", 4089), HostHandler)
+    threading.Thread(target=host_server.serve_forever, daemon=True).start()
     ThreadingHTTPServer(("0.0.0.0", int(os.environ.get("NESTBOX_CONTROL_PORT", "4088"))), Handler).serve_forever()
 
 

package/docker-compose.yaml

@@ -114,6 +114,8 @@ services:
       dockerfile: ./docker/control/Dockerfile
     expose:
       - "4088"
+      # Authenticated host-runner transport, proxied only through Nginx.
+      - "4089"
     volumes:
       - ${DOCKER_SOCKET_PATH:-/var/run/docker.sock}:/var/run/docker.sock
       - type: bind
@@ -123,14 +125,15 @@ services:
         bind:
           create_host_path: false
       - type: bind
-        source: ${NESTBOX_HOST_QUEUE_PATH:?NESTBOX_HOST_QUEUE_PATH must be configured}
-        target: /host-runner
+        source: ${NESTBOX_HOST_TOKEN_FILE:?NESTBOX_HOST_TOKEN_FILE must be configured}
+        target: /run/secrets/nestbox-host-token
+        read_only: true
         bind:
           create_host_path: false
     environment:
       - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}
       - NESTBOX_CONTROL_SERVICE=control
-      - NESTBOX_HOST_RUNNER_PATH=/host-runner
+      - NESTBOX_HOST_TOKEN_FILE=/run/secrets/nestbox-host-token
       - NESTBOX_CONTROL_LOG_OUTPUT=${NESTBOX_CONTROL_LOG_OUTPUT:-text}
       - NESTBOX_CONTROL_LOG_MAX_BYTES=${NESTBOX_CONTROL_LOG_MAX_BYTES:-262144}
     healthcheck:

package/home/configs/nginx/nginx.conf

@@ -74,6 +74,23 @@ http {
             nchan_eventsource_ping_interval 20s;
         }
 
+        # Authenticated native host-runner transport. Control remains private;
+        # this route shares the one published Nestbox gateway port.
+        location ^~ /_nestbox/host/ {
+            resolver 127.0.0.11 ipv6=off valid=10s;
+            set $nestbox_host_control http://control:4089;
+            rewrite ^/_nestbox(/host/.*)$ $1 break;
+            proxy_pass $nestbox_host_control;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_buffering off;
+            proxy_request_buffering off;
+            proxy_read_timeout 40s;
+            client_max_body_size 64m;
+        }
+
         location ^~ /_nestbox/ {
             return 404;
         }

package/home/configs/opencode/control-mcp.js

@@ -74,7 +74,7 @@ async function call(name, raw) {
 
 function emit(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
 async function handle(message) {
-  if (message.method === 'initialize') return emit({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nestbox-control-mcp', version: '0.2.0' } } });
+  if (message.method === 'initialize') return emit({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nestbox-control-mcp', version: '0.4.0' } } });
   if (message.method === 'initialized') return;
   if (message.method === 'tools/list') return emit({ jsonrpc: '2.0', id: message.id, result: { tools } });
   if (message.method === 'tools/call') {