@p10i/create-nestbox 0.3.0 → 0.4.0

package/.env.example

@@ -8,9 +8,8 @@ COMPOSE_PROJECT_NAME=nestbox-change-me
 # directory, or .. when this installation is <workspace>/.nestbox.
 WORKSPACE_PATH=.
 
-# Loopback-only endpoint used by the native host runner. The creator generates
-# a private token; do not expose this port beyond the local host.
-NESTBOX_CONTROL_HOST_PORT=4089
+# 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.

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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`.

package/INSTALL.md

@@ -102,8 +102,7 @@ Configure the host bridge in the workspace root before Compose starts:
 - 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.
 - 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.
-- Confirm that `NESTBOX_CONTROL_HOST_PORT`, normally `4089`, is available. Compose publishes this authenticated runner endpoint on host loopback only.
-- Start `npm run host --` after `control` is healthy. The runner authenticates, long-polls for work, sends heartbeats, and posts results without opening a host listener or sharing queue files.
+- 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:
@@ -121,7 +120,6 @@ Then ask about:
 
 - a unique lowercase `COMPOSE_PROJECT_NAME`;
 - whether to use default port `4180`; verify availability and ask before choosing another port;
-- whether host-runner port `4089` is available; keep it loopback-only;
 - loopback-only or network access;
 - OpenCode username and password;
 - AI providers;

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 native runner authenticates with an external token file mounted only into `control`, long-polls a loopback-only endpoint, and posts results; no host server 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.
+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.
 

package/docker/control/server.py

@@ -372,7 +372,7 @@ def valid_command(command):
 
 
 class Handler(BaseHTTPRequestHandler):
-    server_version = "nestbox-control/0.3"
+    server_version = "nestbox-control/0.4"
 
     def setup(self):
         super().setup()
@@ -560,7 +560,7 @@ class Handler(BaseHTTPRequestHandler):
 
 
 class HostHandler(BaseHTTPRequestHandler):
-    server_version = "nestbox-host-control/0.3"
+    server_version = "nestbox-host-control/0.4"
 
     def setup(self):
         super().setup()
@@ -651,7 +651,7 @@ def main():
         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", int(os.environ.get("NESTBOX_CONTROL_HOST_PORT", "4089"))), HostHandler)
+    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,9 +114,8 @@ services:
       dockerfile: ./docker/control/Dockerfile
     expose:
       - "4088"
-    ports:
-      # Authenticated native runner transport; never bind beyond loopback.
-      - "127.0.0.1:${NESTBOX_CONTROL_HOST_PORT:-4089}:4089"
+      # Authenticated host-runner transport, proxied only through Nginx.
+      - "4089"
     volumes:
       - ${DOCKER_SOCKET_PATH:-/var/run/docker.sock}:/var/run/docker.sock
       - type: bind
@@ -134,7 +133,6 @@ services:
     environment:
       - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}
       - NESTBOX_CONTROL_SERVICE=control
-      - NESTBOX_CONTROL_HOST_PORT=4089
       - 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}

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.3.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') {

package/home/configs/opencode/instructions.md

@@ -204,7 +204,7 @@ The default Compose application has five services:
 - `opencode`: runs this agent, mounts the engine and workspace, and edits the page tree through `/nestbox/home/code`.
 - `control`: owns the Docker socket and privately brokers label-gated container exec and host-runner jobs.
 
-The default host port is `4180` after installer confirmation. Nginx container port `80` serves both Nestbox and OpenCode through host-based routing. Nginx container port `8080` is only the internal Nchan publisher.
+The default host port is `4180` after installer confirmation. Nginx container port `80` serves Nestbox, OpenCode through host-based routing, and the authenticated `/_nestbox/host/` runner transport. Nginx container port `8080` is only the internal Nchan publisher. No other service publishes a host port.
 
 Important files:
 
@@ -226,6 +226,7 @@ The engine's untracked `/nestbox/.env` controls runtime paths, exposure, authent
 - `COMPOSE_PROJECT_NAME`: unique installation identifier; collisions can mix unrelated containers and networks.
 - `BIND_ADDRESS`: loopback for local use or an explicitly approved network bind.
 - `WEB_PORT`: confirmed host gateway port, normally `4180`.
+- `NESTBOX_HOST_TOKEN_FILE`: creator-managed private runner token outside the mounted workspace; only `control` receives it.
 - `APP_UID` and `APP_GID`: PHP-FPM ownership for writable bind mounts.
 - `NESTBOX_URL_PREFIX`: public path prefix when an outer proxy strips that prefix before forwarding.
 - `NESTBOX_OPENCODE_PUBLIC_URL`: explicit public OpenCode origin when `agent.<nestbox-host>` cannot be derived.

package/host-runner.mjs

@@ -24,7 +24,11 @@ function parseEnv(contents) {
 }
 
 const fileEnv = await readFile(join(installDirectory, '.env'), 'utf8').then(parseEnv, error => error?.code === 'ENOENT' ? {} : Promise.reject(error));
-const controlUrl = (process.env.NESTBOX_CONTROL_HOST_URL || fileEnv.NESTBOX_CONTROL_HOST_URL || `http://127.0.0.1:${process.env.NESTBOX_CONTROL_HOST_PORT || fileEnv.NESTBOX_CONTROL_HOST_PORT || '4089'}`).replace(/\/$/, '');
+const bindAddress = process.env.BIND_ADDRESS || fileEnv.BIND_ADDRESS || '127.0.0.1';
+const gatewayAddress = bindAddress === '0.0.0.0' ? '127.0.0.1' : bindAddress === '::' ? '::1' : bindAddress;
+const gatewayHost = gatewayAddress.includes(':') && !gatewayAddress.startsWith('[') ? `[${gatewayAddress}]` : gatewayAddress;
+const webPort = process.env.WEB_PORT || fileEnv.WEB_PORT || '4180';
+const controlUrl = (process.env.NESTBOX_CONTROL_HOST_URL || fileEnv.NESTBOX_CONTROL_HOST_URL || `http://${gatewayHost}:${webPort}/_nestbox`).replace(/\/$/, '');
 const tokenPath = process.env.NESTBOX_HOST_TOKEN_FILE || fileEnv.NESTBOX_HOST_TOKEN_FILE || '';
 const resolvedTokenPath = tokenPath ? await realpath(resolve(tokenPath)).catch(() => resolve(tokenPath)) : '';
 function containsPath(root, target) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p10i/create-nestbox",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Create Nestbox projects.",
   "license": "MIT",
   "type": "module",

package/tests/host-runner.mjs

@@ -30,16 +30,16 @@ const server = createServer(async (request, response) => {
   if (request.headers.authorization !== `Bearer ${token}` || !request.headers['x-nestbox-runner-id']) {
     response.writeHead(401).end('{"error":"unauthorized"}'); return;
   }
-  if (request.method === 'POST' && request.url === '/host/heartbeat') {
+  if (request.method === 'POST' && request.url === '/_nestbox/host/heartbeat') {
     if (heartbeatConflicts > 0) { heartbeatConflicts -= 1; response.writeHead(409).end('{"error":"another host runner is active"}'); return; }
     await readBody(request); response.writeHead(200, { 'content-type': 'application/json' }).end('{"ok":true}'); return;
   }
-  if (request.method === 'GET' && request.url.startsWith('/host/jobs/next')) {
+  if (request.method === 'GET' && request.url.startsWith('/_nestbox/host/jobs/next')) {
     const job = jobs.shift();
     if (!job) { response.writeHead(204).end(); return; }
     response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(job)); return;
   }
-  const match = request.url.match(/^\/host\/jobs\/([^/]+)\/result$/);
+  const match = request.url.match(/^\/_nestbox\/host\/jobs\/([^/]+)\/result$/);
   if (request.method === 'POST' && match) {
     const jobId = decodeURIComponent(match[1]);
     const result = await readBody(request);
@@ -89,7 +89,7 @@ try {
   await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolveListen); });
   const port = server.address().port;
   runner = spawn(process.execPath, [runnerPath, '--json'], {
-    env: { ...process.env, npm_execpath: '', NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}`, NESTBOX_HOST_TOKEN_FILE: tokenPath, NESTBOX_HOST_TOKEN: '' },
+    env: { ...process.env, npm_execpath: '', NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}/_nestbox`, NESTBOX_HOST_TOKEN_FILE: tokenPath, NESTBOX_HOST_TOKEN: '' },
     stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
   });
   let runnerStderr = '';
@@ -119,7 +119,7 @@ try {
   runner.kill('SIGTERM'); await exit; runner = undefined;
 
   const onceRunner = spawn(process.execPath, [runnerPath, '--once', '--json'], {
-    env: { ...process.env, npm_execpath: '', NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}`, NESTBOX_HOST_TOKEN_FILE: tokenPath, NESTBOX_HOST_TOKEN: '' },
+    env: { ...process.env, npm_execpath: '', NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}/_nestbox`, NESTBOX_HOST_TOKEN_FILE: tokenPath, NESTBOX_HOST_TOKEN: '' },
     stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
   });
   const onceExit = await Promise.race([
@@ -131,7 +131,7 @@ try {
   const unsafeToken = join(fixture, 'unsafe-token');
   await writeFile(unsafeToken, `${token}\n`);
   const unsafe = spawnSync(process.execPath, [runnerPath, '--once'], {
-    env: { ...process.env, NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}`, NESTBOX_HOST_TOKEN_FILE: unsafeToken, NESTBOX_HOST_TOKEN: '' }, encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, NESTBOX_HOST_WORKSPACE: fixture, NESTBOX_CONTROL_HOST_URL: `http://127.0.0.1:${port}/_nestbox`, NESTBOX_HOST_TOKEN_FILE: unsafeToken, NESTBOX_HOST_TOKEN: '' }, encoding: 'utf8', windowsHide: true,
   });
   if (unsafe.status === 0 || !unsafe.stderr.includes('must be outside')) throw new Error('Runner accepted a token inside the workspace.');
   console.log('Host runner HTTP tests passed.');

package/tests/nestbox.ps1

@@ -253,7 +253,9 @@ try {
     $controlInspect = @(& docker inspect $controlId 2>$null | ConvertFrom-Json)[0]
     if ($null -eq $controlInspect.NetworkSettings.Ports.'4088/tcp') { Pass 'Control API is not published on the host' } else { Fail 'Control API is published on the host' }
     $runnerBinding = $controlInspect.NetworkSettings.Ports.'4089/tcp'
-    if ($null -ne $runnerBinding -and @($runnerBinding.HostIp) -notcontains '0.0.0.0' -and @($runnerBinding.HostIp) -notcontains '::') { Pass 'Host runner API is published on loopback only' } else { Fail 'Host runner API is not restricted to loopback' }
+    if ($null -eq $runnerBinding) { Pass 'Host runner API is not published separately' } else { Fail 'Host runner API is published separately' }
+    $response = Invoke-Http '/_nestbox/host/health'
+    if ($response.Status -eq 401) { Pass 'Nginx routes the authenticated host runner API' } else { Fail "Host runner gateway returned HTTP $($response.Status) instead of 401" }
     $openCodeId = Get-ContainerId 'opencode'
     $openCodeInspect = @(& docker inspect $openCodeId 2>$null | ConvertFrom-Json)[0]
     if (@($openCodeInspect.Mounts.Destination) -notcontains '/var/run/docker.sock') { Pass 'OpenCode does not receive the Docker socket' } else { Fail 'OpenCode receives the Docker socket' }

package/tests/nestbox.sh

@@ -348,7 +348,9 @@ control_id="$(container_id control)"
 control_binding="$(docker inspect --format '{{json (index .NetworkSettings.Ports "4088/tcp")}}' "$control_id" 2>/dev/null || true)"
 [[ -z "$control_binding" || "$control_binding" == "null" ]] && pass 'Control API is not published on the host' || fail 'Control API is published on the host'
 runner_binding="$(docker inspect --format '{{json (index .NetworkSettings.Ports "4089/tcp")}}' "$control_id" 2>/dev/null || true)"
-if [[ "$runner_binding" == *'"HostIp":"127.0.0.1"'* || "$runner_binding" == *'"HostIp":"::1"'* ]]; then pass 'Host runner API is published on loopback only'; else fail 'Host runner API is not restricted to loopback'; fi
+[[ -z "$runner_binding" || "$runner_binding" == "null" ]] && pass 'Host runner API is not published separately' || fail 'Host runner API is published separately'
+status="$(http_request '/_nestbox/host/health' 2>/dev/null || printf '000')"
+[[ "$status" == "401" ]] && pass 'Nginx routes the authenticated host runner API' || fail "Host runner gateway returned HTTP $status instead of 401"
 opencode_id="$(container_id opencode)"
 opencode_mounts="$(docker inspect --format '{{range .Mounts}}{{println .Source .Destination}}{{end}}' "$opencode_id" 2>/dev/null || true)"
 grep -Fq '/var/run/docker.sock' <<<"$opencode_mounts" && fail 'OpenCode receives the Docker socket' || pass 'OpenCode does not receive the Docker socket'