neoagent 3.0.1-beta.8 → 3.1.0

package/server/services/runtime/docker-vm-manager.js

@@ -1,19 +1,25 @@
 'use strict';
 
 const { spawnSync } = require('child_process');
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
 const net = require('net');
 const { AGENT_DATA_DIR } = require('../../../runtime/paths');
 const { sanitizeWorkspaceKey } = require('../workspace/manager');
+const { GuestImageBuilder, dockerAvailable } = require('./guest_image');
 
-const CONTAINER_IMAGE = 'mcr.microsoft.com/playwright:v1.44.0-focal';
 const CONTAINER_LABEL = 'neoagent.managed=1';
 // The per-user host workspace is bind-mounted here so the shell (execute_command)
 // and the workspace file tools (read_file/write_file/list_directory/search_files)
-// operate on the SAME files. The guest agent defaults its shell cwd to this path.
+// operate on the SAME files. The guest agent's shell defaults its cwd to this path.
 const GUEST_WORKSPACE = '/workspace';
+// Where the guest agent keeps its own runtime files (screenshots, uploads) inside
+// the container — separate from the user workspace bind mount.
+const GUEST_RUNTIME_HOME = '/opt/neoagent/.runtime';
+
+const IS_LINUX = process.platform === 'linux';
 
 // Host path of a user's workspace — must match WorkspaceManager's layout exactly
 // (AGENT_DATA_DIR/workspaces/<sanitized key>) so both sides see one directory.
@@ -21,233 +27,25 @@ function hostWorkspaceDir(key) {
   return path.join(AGENT_DATA_DIR, 'workspaces', sanitizeWorkspaceKey(key));
 }
 
-// ─── Guest agent ─────────────────────────────────────────────────────────────
-// Injected into every container. Pure Node.js — only built-in modules + playwright
-// (installed at /tmp/pw after container start). Served on $AGENT_PORT.
-const GUEST_AGENT = `
-const http = require('http');
-const { spawn } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-const PORT = parseInt(process.env.AGENT_PORT || '3000', 10);
-const SCREENSHOTS = '/tmp/screenshots';
-fs.mkdirSync(SCREENSHOTS, { recursive: true });
-
-const procs = new Map();
-let browser = null, page = null, pw = null;
-
-function loadPlaywright() {
-  if (pw) return pw;
-  try { pw = require('/tmp/pw/node_modules/playwright'); return pw; } catch { return null; }
-}
-
-function chromiumExec() {
-  const base = '/ms-playwright';
-  if (!fs.existsSync(base)) return null;
-  for (const dir of fs.readdirSync(base)) {
-    if (!dir.startsWith('chromium')) continue;
-    const bin = base + '/' + dir + '/chrome-linux/chrome';
-    if (fs.existsSync(bin)) return bin;
-  }
-  return null;
-}
-
-function json(res, data, status) {
-  const body = JSON.stringify(data);
-  res.writeHead(status || 200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
-  res.end(body);
+// Workspace bind mount. On SELinux-enforcing Linux hosts (Fedora/RHEL/Rocky) the
+// `:Z` suffix relabels the directory to a container-private context so the guest
+// can read/write it; it is a no-op elsewhere. On macOS, Docker Desktop maps file
+// ownership automatically, so no suffix is needed.
+function workspaceMount(hostDir) {
+  return IS_LINUX ? `${hostDir}:${GUEST_WORKSPACE}:Z` : `${hostDir}:${GUEST_WORKSPACE}`;
 }
 
-const MAX_BODY_BYTES = 1 * 1024 * 1024;
-
-function body(req) {
-  return new Promise((resolve, reject) => {
-    let s = '', size = 0;
-    req.on('data', d => {
-      size += d.length;
-      if (size > MAX_BODY_BYTES) { req.destroy(); reject(Object.assign(new Error('Request body too large'), { status: 413 })); return; }
-      s += d;
-    });
-    req.on('end', () => { try { resolve(JSON.parse(s)); } catch { resolve({}); } });
-    req.on('error', err => reject(err));
-  });
-}
-
-async function screenshot(label) {
-  if (!page) return null;
-  const p = path.join(SCREENSHOTS, label + '.png');
-  await page.screenshot({ path: p, fullPage: false });
-  return p;
-}
-
-async function ensureBrowser() {
-  if (browser) return;
-  const lib = loadPlaywright();
-  if (!lib) throw new Error('Playwright not ready — container still installing dependencies. Retry in a moment.');
-  const exec = chromiumExec();
-  browser = await lib.chromium.launch({ headless: true, executablePath: exec || undefined, args: ['--no-sandbox', '--disable-setuid-sandbox'] });
-  try {
-    const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 } });
-    page = await ctx.newPage();
-  } catch (err) {
-    await browser.close().catch(() => {});
-    browser = null;
-    page = null;
-    throw err;
+// On Linux the container shares the host kernel, so files the guest creates in the
+// bind mount would be owned by the container user. Run as the host uid:gid so the
+// NeoAgent process (and its file tools) can read and modify them. On macOS the
+// Docker Desktop VM virtualizes ownership, so the default container user is fine.
+function hostUserArgs() {
+  if (IS_LINUX && typeof process.getuid === 'function') {
+    return ['--user', `${process.getuid()}:${process.getgid()}`];
   }
+  return [];
 }
 
-const server = http.createServer(async (req, res) => {
-  try {
-    const url = req.url.split('?')[0];
-
-    if (req.method === 'GET' && url === '/health') {
-      return json(res, { status: 'ok' });
-    }
-
-    if (req.method === 'GET' && url === '/browser/status') {
-      const info = page ? await page.evaluate(() => ({ url: location.href, title: document.title })).catch(() => ({})) : {};
-      const pageInfo = page ? { url: info.url || null, title: info.title || null } : null;
-      return json(res, { launched: !!browser, pageInfo, pageCount: page ? 1 : 0 });
-    }
-
-    const b = await body(req);
-
-    // ── CLI execution ──────────────────────────────────────────────────────
-    if (req.method === 'POST' && url === '/exec') {
-      const timeoutMs = Math.min(Number(b.timeout) || 15 * 60 * 1000, 20 * 60 * 1000);
-      const child = spawn('sh', ['-c', b.command || 'true'], {
-        cwd: b.cwd || '/workspace',
-        env: { ...process.env, ...b.env },
-      });
-      const pid = child.pid;
-      let stdout = '', stderr = '', settled = false;
-      procs.set(pid, child);
-      child.stdout.on('data', d => { stdout += d; });
-      child.stderr.on('data', d => { stderr += d; });
-      const timer = setTimeout(() => {
-        if (settled) return;
-        settled = true;
-        procs.delete(pid);
-        try { child.kill('SIGKILL'); } catch {}
-        json(res, { stdout, stderr, exitCode: null, code: null, pid, timedOut: true, killed: true });
-      }, timeoutMs);
-      child.on('close', code => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        procs.delete(pid);
-        const exitCode = code ?? 1;
-        json(res, { stdout, stderr, exitCode, code: exitCode, pid, timedOut: false, killed: false });
-      });
-      child.on('error', err => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        procs.delete(pid);
-        json(res, { stdout, stderr, exitCode: 1, code: 1, pid, error: err.message, timedOut: false, killed: false });
-      });
-      return;
-    }
-
-    if (req.method === 'POST' && url === '/exec/kill') {
-      const child = procs.get(b.pid);
-      try { child?.kill('SIGKILL'); } catch {}
-      return json(res, { success: true });
-    }
-
-    // ── File access ────────────────────────────────────────────────────────
-    if (req.method === 'POST' && url === '/files/read') {
-      try {
-        const content = fs.readFileSync(b.path, 'base64');
-        return json(res, { content });
-      } catch (err) {
-        return json(res, { error: err.message }, 404);
-      }
-    }
-
-    // ── Browser ────────────────────────────────────────────────────────────
-    if (req.method === 'POST' && url === '/browser/launch') {
-      await ensureBrowser();
-      return json(res, { success: true });
-    }
-
-    if (req.method === 'POST' && url === '/browser/close') {
-      if (browser) { await browser.close().catch(() => {}); browser = null; page = null; }
-      return json(res, { success: true });
-    }
-
-    if (req.method === 'POST' && url === '/browser/navigate') {
-      await ensureBrowser();
-      await page.goto(b.url, { waitUntil: b.waitUntil || 'domcontentloaded', timeout: b.timeout || 30000 });
-      const info = await page.evaluate(() => ({ url: location.href, title: document.title }));
-      const screenshotPath = b.screenshot !== false ? await screenshot('nav-' + Date.now()) : null;
-      return json(res, { url: info.url, title: info.title, screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/screenshot') {
-      await ensureBrowser();
-      return json(res, { screenshotPath: await screenshot('ss-' + Date.now()) });
-    }
-
-    if (req.method === 'POST' && url === '/browser/click') {
-      if (b.selector) await page.click(b.selector, { timeout: 10000 }).catch(() => {});
-      const screenshotPath = b.screenshot !== false ? await screenshot('click-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/click-point') {
-      await page.mouse.click(b.x, b.y);
-      const screenshotPath = b.screenshot !== false ? await screenshot('clickpt-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/fill') {
-      await page.fill(b.selector, b.value || b.text || '', { timeout: 10000 });
-      const screenshotPath = b.screenshot !== false ? await screenshot('fill-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/type-text') {
-      await page.keyboard.type(b.text || '');
-      const screenshotPath = b.screenshot !== false ? await screenshot('type-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/press-key') {
-      await page.keyboard.press(b.key || '');
-      const screenshotPath = b.screenshot !== false ? await screenshot('key-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/scroll') {
-      await page.evaluate(({ x, y }) => window.scrollBy(x, y), { x: b.deltaX || 0, y: b.deltaY || 0 });
-      const screenshotPath = b.screenshot !== false ? await screenshot('scroll-' + Date.now()) : null;
-      return json(res, { screenshotPath });
-    }
-
-    if (req.method === 'POST' && url === '/browser/extract') {
-      const result = b.all
-        ? await page.$$(b.selector).then(els => Promise.all(els.map(el => el.getAttribute(b.attribute).catch(() => null))))
-        : await page.$(b.selector).then(el => el ? el.getAttribute(b.attribute) : null);
-      return json(res, { result });
-    }
-
-    if (req.method === 'POST' && url === '/browser/execute') {
-      const result = await page.evaluate(b.script || b.code || '').catch(err => ({ error: err.message }));
-      return json(res, { result });
-    }
-
-    json(res, { error: 'Not found' }, 404);
-  } catch (err) {
-    json(res, { error: err.message }, err.status || 500);
-  }
-});
-
-server.listen(PORT, '0.0.0.0', () => process.stdout.write('AGENT_READY\\n'));
-`.trim();
-
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function findAvailablePort() {
@@ -273,17 +71,25 @@ function isContainerRunning(containerId) {
   catch { return false; }
 }
 
+function containerLogs(containerId, tailLines = 20) {
+  try { return docker(['logs', '--tail', String(tailLines), containerId], { timeout: 5000 }); }
+  catch { return ''; }
+}
+
+// Resolve once the guest agent's HTTP server is accepting connections. Any HTTP
+// response (including 401 when a guest token is required) proves the process is
+// listening; the authenticated health probe happens in the execution backend.
 function waitForAgent(port, timeoutMs) {
   return new Promise((resolve, reject) => {
-    const deadline = Date.now() + (timeoutMs || 180000);
+    const deadline = Date.now() + (timeoutMs || 120000);
     function attempt() {
-      if (Date.now() > deadline) return reject(new Error(`Agent on port ${port} not ready within ${Math.round((timeoutMs || 180000) / 1000)}s`));
-      const req = http.get(`http://localhost:${port}/health`, res => {
-        if (res.statusCode === 200) return resolve();
-        setTimeout(attempt, 3000);
+      if (Date.now() > deadline) return reject(new Error(`Agent on port ${port} not ready within ${Math.round((timeoutMs || 120000) / 1000)}s`));
+      const req = http.get(`http://localhost:${port}/health`, (res) => {
+        res.resume();
+        return resolve();
       });
-      req.on('error', () => setTimeout(attempt, 3000));
-      req.setTimeout(2000, () => { req.destroy(); setTimeout(attempt, 3000); });
+      req.on('error', () => setTimeout(attempt, 1000));
+      req.setTimeout(2000, () => { req.destroy(); setTimeout(attempt, 1000); });
     }
     attempt();
   });
@@ -292,19 +98,91 @@ function waitForAgent(port, timeoutMs) {
 // ─── DockerVMManager ─────────────────────────────────────────────────────────
 
 class DockerVMManager {
-  /** @type {Map<string, {baseUrl:string, guestToken:null, process:{pid:number}, getLastError:()=>null, containerId:string}>} */
+  /** @type {Map<string, {baseUrl:string, guestToken:string|null, process:{pid:number}, getLastError:()=>(string|null), containerId:string}>} */
   instances = new Map();
   #pending = new Map();
   #readiness = null;
   #readinessAt = 0;
 
   constructor(options = {}) {
-    this.profile = options.runtimeProfile || 'default';
-    this.image = options.image || CONTAINER_IMAGE;
+    this.profile = options.runtimeProfile || 'browser_cli';
     this.memoryMb = options.memoryMb || 2048;
     this.cpus = options.cpus || 2;
-    this.guestToken = String(options.guestToken || process.env.NEOAGENT_VM_GUEST_TOKEN || '').trim();
+    this.pidsLimit = Number(options.pidsLimit || process.env.NEOAGENT_VM_PIDS_LIMIT || 512);
+    // The guest agent authenticates every request with this token. Always have
+    // one — fall back to a per-process random secret if the operator didn't set
+    // NEOAGENT_VM_GUEST_TOKEN so the sandbox is never left unauthenticated.
+    this.guestToken = String(options.guestToken || process.env.NEOAGENT_VM_GUEST_TOKEN || '').trim()
+      || crypto.randomBytes(32).toString('hex');
+    this.imageBuilder = options.imageBuilder || new GuestImageBuilder({ runtimeProfile: this.profile });
+    this.bootTimeoutMs = Number(options.bootTimeoutMs || process.env.NEOAGENT_VM_BOOT_TIMEOUT_MS || 120000);
+    this.network = null;
     this.#cleanupOrphans();
+    this.#setupNetwork();
+  }
+
+  // Put agent containers on a dedicated bridge network so their egress can be
+  // firewalled away from cloud instance-metadata endpoints.
+  #setupNetwork() {
+    if (String(process.env.NEOAGENT_VM_EGRESS_FIREWALL ?? '1') === '0') {
+      return;
+    }
+    const name = 'neoagent-agents';
+    try {
+      let subnet = '';
+      try {
+        subnet = docker(['network', 'inspect', '--format', '{{range .IPAM.Config}}{{.Subnet}}{{end}}', name]);
+      } catch {
+        docker(['network', 'create', name]);
+        subnet = docker(['network', 'inspect', '--format', '{{range .IPAM.Config}}{{.Subnet}}{{end}}', name]);
+      }
+      this.network = name;
+      if (subnet) {
+        this.#applyEgressFirewall(subnet.trim());
+      }
+    } catch (err) {
+      // Without the dedicated network we fall back to the default bridge; the
+      // dropped NET_RAW/NET_ADMIN capabilities still apply as defense in depth.
+      console.warn(`[DockerVM:${this.profile}] Could not set up isolated network — metadata egress not firewalled: ${err.message}`);
+      this.network = null;
+    }
+  }
+
+  #applyEgressFirewall(subnet) {
+    // The host egress firewall is enforced with iptables, which only exists on
+    // Linux hosts. On macOS/Windows the Docker daemon runs in a managed VM with
+    // no cloud metadata endpoint to protect, so the dedicated network alone
+    // (namespace isolation) is sufficient.
+    if (!IS_LINUX) {
+      return;
+    }
+    // Cloud instance-metadata endpoints across the major providers.
+    const blockedHosts = ['169.254.169.254/32', '169.254.170.2/32', '100.100.100.200/32'];
+    // Self-hosters keep LAN access by default (mirrors NEOAGENT_HTTP_ALLOW_PRIVATE);
+    // cloud operators can set it to false to also cut off RFC-1918 ranges.
+    const allowPrivate = String(process.env.NEOAGENT_HTTP_ALLOW_PRIVATE ?? 'true').toLowerCase() !== 'false';
+    const blockedNets = allowPrivate ? [] : ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'];
+    const targets = [...blockedHosts, ...blockedNets];
+
+    let applied = 0;
+    for (const dest of targets) {
+      const spec = ['DOCKER-USER', '-s', subnet, '-d', dest, '-j', 'DROP'];
+      try {
+        const check = spawnSync('iptables', ['-C', ...spec], { encoding: 'utf8' });
+        if (check.status !== 0) {
+          const insert = spawnSync('iptables', ['-I', ...spec], { encoding: 'utf8' });
+          if (insert.status !== 0) {
+            throw new Error((insert.stderr || `exit ${insert.status}`).trim());
+          }
+        }
+        applied += 1;
+      } catch (err) {
+        console.warn(`[DockerVM:${this.profile}] Unable to install egress firewall rule for ${dest} (need root/NET_ADMIN on host): ${err.message}. Sandbox containers may be able to reach ${dest}.`);
+      }
+    }
+    if (applied > 0) {
+      console.log(`[DockerVM:${this.profile}] Egress firewall active — blocking ${applied} destination(s) from sandbox subnet ${subnet}`);
+    }
   }
 
   // Remove containers left over from a previous server run.
@@ -326,6 +204,14 @@ class DockerVMManager {
     const existing = this.instances.get(key);
     if (existing && isContainerRunning(existing.containerId)) return existing;
 
+    // Stale entry: the guest agent runs as the container's main process, so if it
+    // crashed the container has stopped. Remove the dead container before starting
+    // a fresh one (automatic crash recovery).
+    if (existing) {
+      this.instances.delete(key);
+      try { docker(['rm', '-f', existing.containerId]); } catch { /* already gone */ }
+    }
+
     // Already starting for this user — share the in-flight promise.
     const inflight = this.#pending.get(key);
     if (inflight) return inflight;
@@ -336,6 +222,7 @@ class DockerVMManager {
   }
 
   async #startContainer(key) {
+    const image = await this.imageBuilder.ensure();
     const port = await findAvailablePort();
     console.log(`[DockerVM:${this.profile}] Starting container for user ${key} on port ${port}`);
 
@@ -347,49 +234,51 @@ class DockerVMManager {
       'run', '-d',
       '--memory', `${this.memoryMb}m`,
       '--cpus', String(this.cpus),
+      '--pids-limit', String(this.pidsLimit),
+      ...hostUserArgs(),
       '-p', `127.0.0.1:${port}:${port}`,
-      '-e', `AGENT_PORT=${port}`,
-      ...(this.guestToken ? ['-e', `NEOAGENT_VM_GUEST_TOKEN=${this.guestToken}`] : []),
+      ...(this.network ? ['--network', this.network] : []),
+      '-e', `NEOAGENT_GUEST_AGENT_PORT=${port}`,
+      '-e', `HOME=${GUEST_WORKSPACE}`,
+      '-e', `NEOAGENT_HOME=${GUEST_RUNTIME_HOME}`,
+      '-e', `NEOAGENT_VM_GUEST_TOKEN=${this.guestToken}`,
       '--shm-size=2g',
       '--security-opt', 'no-new-privileges',
-      '-v', `${workspaceDir}:${GUEST_WORKSPACE}`,
-      '-w', GUEST_WORKSPACE,
+      // Strip capabilities the sandbox never needs. Dropping NET_RAW/NET_ADMIN
+      // also prevents the container from crafting raw packets or rewriting its
+      // own routing/iptables to bypass the host egress firewall above.
+      '--cap-drop', 'NET_RAW',
+      '--cap-drop', 'NET_ADMIN',
+      '--cap-drop', 'SYS_ADMIN',
+      '--cap-drop', 'SYS_PTRACE',
+      '--cap-drop', 'SYS_MODULE',
+      '-v', workspaceMount(workspaceDir),
       '--label', CONTAINER_LABEL,
       '--label', `neoagent.profile=${this.profile}`,
       '--label', `neoagent.user=${key}`,
-      this.image,
-      'sleep', 'infinity',
-    ]);
-    console.log(`[DockerVM:${this.profile}] Container ${containerId.slice(0, 12)} started`);
-
-    // Inject agent source file
-    spawnSync('docker', ['exec', '-i', containerId, 'sh', '-c', 'cat > /tmp/agent.js'], {
-      input: GUEST_AGENT, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    // Install playwright then start agent (detached so npm install doesn't block)
-    docker(['exec', '-d', containerId, 'sh', '-c',
-      'npm install playwright --prefix /tmp/pw > /tmp/pw-install.log 2>&1 && node /tmp/agent.js',
+      image,
     ]);
+    console.log(`[DockerVM:${this.profile}] Container ${containerId.slice(0, 12)} started (${image})`);
 
     const session = {
       baseUrl: `http://localhost:${port}`,
-      guestToken: null,
+      guestToken: this.guestToken || null,
       process: { pid: process.pid }, // server PID — always alive while server runs
-      getLastError: () => null,
+      getLastError: () => containerLogs(containerId) || null,
       containerId,
     };
     this.instances.set(key, session);
 
-    console.log(`[DockerVM:${this.profile}] Waiting for agent on port ${port}…`);
+    console.log(`[DockerVM:${this.profile}] Waiting for guest agent on port ${port}…`);
     try {
-      await waitForAgent(port, 180000);
+      await waitForAgent(port, this.bootTimeoutMs);
     } catch (err) {
+      const logs = containerLogs(containerId);
       this.instances.delete(key);
-      try { docker(['rm', '-f', containerId]); } catch {}
-      throw err;
+      try { docker(['rm', '-f', containerId]); } catch { /* best effort */ }
+      throw new Error(logs ? `${err.message}\n${logs}` : err.message);
     }
-    console.log(`[DockerVM:${this.profile}] Agent ready — ${session.baseUrl}`);
+    console.log(`[DockerVM:${this.profile}] Guest agent ready — ${session.baseUrl}`);
     return session;
   }
 
@@ -408,7 +297,7 @@ class DockerVMManager {
 
   async shutdown() {
     await Promise.allSettled([...this.#pending.values()]);
-    await Promise.allSettled([...this.instances.keys()].map(k => this.killVm(k)));
+    await Promise.allSettled([...this.instances.keys()].map((k) => this.killVm(k)));
   }
 
   hasVm(userId) {
@@ -417,15 +306,17 @@ class DockerVMManager {
     return Boolean(session && isContainerRunning(session.containerId));
   }
 
-  // Used by validation.js — cached to avoid a docker call on every status poll.
+  // Used by validation.js — cached to avoid docker calls on every status poll.
   getReadiness() {
     const now = Date.now();
     if (this.#readiness && now - this.#readinessAt < 30000) return this.#readiness;
-    try {
-      docker(['info'], { timeout: 5000 });
-      this.#readiness = { ready: true, dockerAvailable: true };
-    } catch {
-      this.#readiness = { ready: false, dockerAvailable: false };
+    if (!dockerAvailable()) {
+      this.#readiness = { ready: false, dockerAvailable: false, imageBuilt: false, image: null };
+    } else {
+      const state = this.imageBuilder.getState();
+      // Docker is the hard requirement; the image is built automatically on first
+      // use, so readiness does not block on it.
+      this.#readiness = { ready: true, dockerAvailable: true, imageBuilt: state.imageBuilt, image: state.image };
     }
     this.#readinessAt = now;
     return this.#readiness;

package/server/services/runtime/guest_bootstrap.js

@@ -35,13 +35,12 @@ function normalizeRuntimeProfile(runtimeProfile) {
   return runtimeProfile === 'android' ? 'android' : 'browser_cli';
 }
 
-function createGuestPayloadArchive(seedDir, runtimeProfile = 'browser_cli') {
-  const seedRoot = path.dirname(seedDir);
-  const stagingRoot = path.join(seedRoot, 'guest-payload');
-  const archivePath = path.join(seedRoot, 'guest-payload.tar.gz');
+// Copy the guest runtime source files for a profile into `stagingRoot`, producing
+// a self-contained directory (package.json + runtime/ + server/) that can be
+// archived for the QEMU path or used as a Docker build context.
+function stageGuestPayload(stagingRoot, runtimeProfile = 'browser_cli') {
   const payloadEntries = GUEST_PAYLOAD_PROFILES[normalizeRuntimeProfile(runtimeProfile)];
   fs.rmSync(stagingRoot, { recursive: true, force: true });
-  fs.rmSync(archivePath, { force: true });
   fs.mkdirSync(stagingRoot, { recursive: true });
 
   for (const entry of payloadEntries) {
@@ -54,6 +53,15 @@ function createGuestPayloadArchive(seedDir, runtimeProfile = 'browser_cli') {
       fs.copyFileSync(sourcePath, targetPath);
     }
   }
+  return stagingRoot;
+}
+
+function createGuestPayloadArchive(seedDir, runtimeProfile = 'browser_cli') {
+  const seedRoot = path.dirname(seedDir);
+  const stagingRoot = path.join(seedRoot, 'guest-payload');
+  const archivePath = path.join(seedRoot, 'guest-payload.tar.gz');
+  fs.rmSync(archivePath, { force: true });
+  stageGuestPayload(stagingRoot, runtimeProfile);
 
   const tarResult = spawnSync('tar', ['-czf', archivePath, '-C', stagingRoot, '.'], {
     encoding: 'utf8',
@@ -651,4 +659,8 @@ module.exports = {
   createSeedIso,
   ensureGuestBootstrapSeed,
   GUEST_BOOTSTRAP_ROOT,
+  GUEST_PAYLOAD_PROFILES,
+  REPO_ROOT,
+  normalizeRuntimeProfile,
+  stageGuestPayload,
 };