From b96152267346ed8fadd3334c23b44882df2014fd Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:33:36 +0800
Subject: [PATCH 1/9] feat(web): initialize zero-node sandbox deployments from
 manager

---
 apps/web/e2e/fixture-sandbox.mjs              |  24 ++-
 apps/web/e2e/sandbox-setup.spec.ts            | 153 ++++++++++++++++++
 .../src/features/sandbox/NodeEnrollment.tsx   |  31 ++++
 .../features/sandbox/SandboxManagerView.css   |   3 +
 .../features/sandbox/SandboxManagerView.tsx   |  47 ++++--
 .../web/src/features/sandbox/SandboxSetup.tsx |  30 ++++
 .../src/features/sandbox/core-origin.test.ts  |  12 ++
 apps/web/src/features/sandbox/core-origin.ts  |   9 ++
 .../agents-client/src/sandbox-client.test.ts  |  26 +++
 packages/agents-client/src/sandbox-client.ts  |   9 +-
 10 files changed, 324 insertions(+), 20 deletions(-)
 create mode 100644 apps/web/e2e/sandbox-setup.spec.ts
 create mode 100644 apps/web/src/features/sandbox/NodeEnrollment.tsx
 create mode 100644 apps/web/src/features/sandbox/SandboxSetup.tsx
 create mode 100644 apps/web/src/features/sandbox/core-origin.test.ts
 create mode 100644 apps/web/src/features/sandbox/core-origin.ts

diff --git a/apps/web/e2e/fixture-sandbox.mjs b/apps/web/e2e/fixture-sandbox.mjs
index 78c51742e..69347f3d5 100644
--- a/apps/web/e2e/fixture-sandbox.mjs
+++ b/apps/web/e2e/fixture-sandbox.mjs
@@ -8,8 +8,9 @@ let nodes = [];
 let calls = [];
 let provider = "docker";
 let diagnostic = "";
+let coreUrl = "";
 export function resetSandboxFixture() {
-  nodes = [node("node-local", "Core server"), node("node-offline", "Offline host", false)]; calls = []; provider = "docker"; diagnostic = "";
+  nodes = [node("node-local", "Core server"), node("node-offline", "Offline host", false)]; calls = []; provider = "docker"; diagnostic = ""; coreUrl = "";
 }
 resetSandboxFixture();
 export function handleSandboxFixture(request, response, url, sendJson, sendError) {
@@ -21,8 +22,10 @@ export function handleSandboxFixture(request, response, url, sendJson, sendError
     nodes = nodes.map((entry) => entry.id === "node-local" ? { ...entry, online: value !== "node_unavailable", provider_ready: value !== "provider_unavailable", diagnostic: value === "provider_unavailable" ? value : "" } : entry);
     sendJson(response, {}); return true;
   }
-  if (path === "/__fixture/sandbox") { sendJson(response, { nodes, calls }); return true; }
+  if (path === "/__fixture/sandbox") { sendJson(response, { nodes, calls, provider, core_url: coreUrl }); return true; }
   if (path === "/__fixture/sandbox-microsandbox") { provider = "microsandbox"; sendJson(response, {}); return true; }
+  if (path === "/__fixture/sandbox-uninitialized") { provider = ""; coreUrl = ""; nodes = []; sendJson(response, {}); return true; }
+  if (path === "/__fixture/sandbox-add-node") { nodes.push({ ...node("node-enrolled", "Enrolled host"), provider }); sendJson(response, {}); return true; }
   const projectRoute = path === "/v1/sandbox/nodes" || /^\/v1\/agents\/sessions\/[^/]+\/sandbox-placement$/.test(path);
   if (projectRoute && request.headers["openai-beta"] !== "agents=v1") {
     sendError(response, 400, "OpenAI-Beta: agents=v1 is required.", "invalid_beta"); return true;
@@ -34,7 +37,22 @@ export function handleSandboxFixture(request, response, url, sendJson, sendError
   if (!path.startsWith("/core/v1/sandbox/")) return false;
   calls.push({ path, method: request.method, authorized: request.headers.authorization === "Bearer fixture-admin-key" });
   if (request.headers.authorization !== "Bearer fixture-admin-key") { sendError(response, 401, "A deployment admin key is required.", "invalid_admin_key"); return true; }
-  if (path.endsWith("/deployment")) sendJson(response, { installation_id: "fixture-installation", provider, maintenance: false, owner_epoch: 1 });
+  const deployment = () => ({ installation_id: "fixture-installation", provider, core_url: coreUrl, maintenance: false, owner_epoch: 1 });
+  if (path.endsWith("/deployment") && request.method === "POST") {
+    let body = "";
+    request.on("data", (chunk) => { body += chunk; });
+    request.on("end", () => {
+      try {
+        const input = JSON.parse(body);
+        if (provider && (provider !== input.provider || coreUrl !== input.core_url)) {
+          sendError(response, 409, "Sandbox deployment is already configured.", "sandbox_deployment_conflict"); return;
+        }
+        provider = input.provider; coreUrl = input.core_url;
+        sendJson(response, deployment());
+      } catch { sendError(response, 400, "Invalid setup request."); }
+    });
+  }
+  else if (path.endsWith("/deployment")) sendJson(response, deployment());
   else if (path.endsWith("/enrollment-tokens")) sendJson(response, { token: "fixture-once-token", expires_at: "2026-09-23T09:00:00Z" });
   else if (path.endsWith("/allocations")) sendJson(response, { data: path.includes("node-local") ? [{ id: "allocation-1", node_id: "node-local", session_id: "session_snapshot", tenant_id: "fixture-project", environment_id: "environment-1", state: "active", compute_phase: "running", initialization: "ready", diagnostic, created_at: now }] : [] });
   else if (request.method === "DELETE") {
diff --git a/apps/web/e2e/sandbox-setup.spec.ts b/apps/web/e2e/sandbox-setup.spec.ts
new file mode 100644
index 000000000..a94234d22
--- /dev/null
+++ b/apps/web/e2e/sandbox-setup.spec.ts
@@ -0,0 +1,153 @@
+import { expect, test, type Page } from "@playwright/test";
+
+const fixture = `http://127.0.0.1:${process.env.AGENTS_FIXTURE_PORT ?? 18092}`;
+const setupUrl = `${fixture}/core/v1/sandbox/deployment`;
+const adminHeaders = { Authorization: "Bearer fixture-admin-key" };
+async function openSetup(page: Page) {
+  await page.getByRole("button", { name: "Hosted Sandbox Manager", exact: true }).click();
+  await page.getByLabel("Deployment admin key").fill("fixture-admin-key");
+  await page.getByRole("button", { name: "Connect admin", exact: true }).click();
+  await expect(page.getByRole("heading", { name: "Set up hosted sandboxes" })).toBeVisible();
+}
+test.beforeEach(async ({ page, request }) => {
+  await request.post(`${fixture}/__fixture/reset`);
+  await request.post(`${fixture}/__fixture/sandbox-uninitialized`);
+  await page.goto("/");
+  await expect(page.getByRole("button", { name: "Sessions", exact: true })).toBeVisible();
+});
+
+for (const provider of ["docker", "microsandbox"]) {
+  test(`initial ${provider} setup, enrollment, refresh and immutable selection`, async ({ page, request }) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await openSetup(page);
+    const submit = page.getByRole("button", { name: "Initialize sandbox deployment" });
+    await expect(submit).toBeDisabled();
+    await expect(page.getByLabel("Sandbox provider")).toHaveValue("");
+    await expect(page.getByRole("button", { name: "Generate enrollment command" })).toHaveCount(0);
+    await page.getByLabel("Sandbox provider").selectOption(provider);
+    const origin = page.getByLabel("Core origin reachable from nodes and guests");
+    for (const invalid of ["http://core.example", "https://core.example/v1", "https://user:secret@core.example", "https://core.example?key=secret"]) {
+      await origin.fill(invalid);
+      await expect(submit).toBeDisabled();
+    }
+    await origin.fill("https://CORE.example/");
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);
+    await submit.click();
+    await expect(page.locator(".sandbox-summary")).toContainText(provider === "docker" ? "Docker" : "microsandbox");
+    await expect(page.getByLabel("Sandbox provider")).toHaveCount(0);
+    await expect(page.getByText("No nodes registered. Add a node to provide hosted capacity.")).toBeVisible();
+    await expect(page.getByLabel("Core URL reachable from the node")).toHaveValue("https://core.example");
+    await expect(page.getByLabel("Core URL reachable from the node")).toHaveAttribute("readonly", "");
+    await expect(page.getByRole("link", { name: "Node configuration guide" })).toBeVisible();
+    await expect(page.locator(".sandbox-steps")).toContainText("fixture-installation");
+    await page.getByRole("button", { name: "Generate enrollment command" }).click();
+    await expect(page.getByLabel("One-time enrollment command")).toHaveValue(/--core-url 'https:\/\/core.example'/);
+    expect(await page.evaluate(() => JSON.stringify({ local: { ...localStorage }, session: { ...sessionStorage } }))).not.toMatch(/fixture-admin-key|fixture-once-token/);
+    await request.post(`${fixture}/__fixture/sandbox-add-node`);
+    await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+    await expect(page.getByRole("region", { name: "Sandbox nodes", exact: true })).toContainText("Enrolled host");
+    await expect(page.getByRole("region", { name: "Sandbox nodes", exact: true })).toContainText("Provider ready");
+    const state = await (await request.get(`${fixture}/__fixture/sandbox`)).json();
+    expect(state.calls.filter((call: { path: string; method: string }) => call.path.endsWith("/deployment") && call.method === "POST")).toHaveLength(1);
+    expect(state.provider).toBe(provider);
+    expect(state.core_url).toBe("https://core.example");
+  });
+}
+
+test("concurrent setup conflict requires refresh and displays the committed provider", async ({ page, request }) => {
+  await openSetup(page);
+  await page.getByLabel("Sandbox provider").selectOption("docker");
+  await page.getByLabel("Core origin reachable from nodes and guests").fill("https://core.example");
+  const winner = { provider: "microsandbox", core_url: "https://other-core.example" };
+  expect((await request.post(setupUrl, { headers: adminHeaders, data: winner })).status()).toBe(200);
+  expect((await request.post(setupUrl, { headers: adminHeaders, data: winner })).status()).toBe(200);
+  await page.getByRole("button", { name: "Initialize sandbox deployment" }).click();
+  await expect(page.getByRole("alert")).toContainText("already configured");
+  await expect(page.getByRole("button", { name: "Initialize sandbox deployment" })).toBeDisabled();
+  await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+  await expect(page.locator(".sandbox-summary")).toContainText("microsandbox");
+  await expect(page.getByLabel("Core URL reachable from the node")).toHaveValue(winner.core_url);
+  await expect(page.getByLabel("Sandbox provider")).toHaveCount(0);
+});
+
+test("a lost setup response is not retried and refresh recovers the saved deployment", async ({ page, request }) => {
+  await openSetup(page);
+  await page.getByLabel("Sandbox provider").selectOption("docker");
+  await page.getByLabel("Core origin reachable from nodes and guests").fill("https://core.example");
+  let writes = 0;
+  await page.route("**/core/v1/sandbox/deployment", async (route) => {
+    if (route.request().method() !== "POST") return route.continue();
+    writes++;
+    await route.fetch();
+    await route.abort("connectionreset");
+  });
+  await page.getByRole("button", { name: "Initialize sandbox deployment" }).click();
+  await expect(page.getByRole("alert")).toContainText("Refresh sandbox state to confirm");
+  await expect(page.getByRole("button", { name: "Initialize sandbox deployment" })).toBeDisabled();
+  expect(writes).toBe(1);
+  await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+  await expect(page.locator(".sandbox-summary")).toContainText("Docker");
+  expect(writes).toBe(1);
+  expect((await (await request.get(setupUrl, { headers: adminHeaders })).json()).provider).toBe("docker");
+});
+
+test("a failed setup refresh keeps setup disabled until a successful read", async ({ page }) => {
+  await openSetup(page);
+  await page.getByLabel("Sandbox provider").selectOption("docker");
+  await page.getByLabel("Core origin reachable from nodes and guests").fill("https://core.example");
+  await page.route("**/core/v1/sandbox/deployment", (route) => route.fulfill({ status: 503, contentType: "application/json", body: JSON.stringify({ error: { message: "Deployment unavailable" } }) }));
+  await page.getByRole("button", { name: "Initialize sandbox deployment" }).click();
+  await expect(page.getByRole("alert")).toContainText("Refresh sandbox state to confirm");
+  await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+  await expect(page.getByRole("alert")).toContainText("Deployment unavailable");
+  await expect(page.getByLabel("Sandbox provider")).toBeDisabled();
+  await page.unroute("**/core/v1/sandbox/deployment");
+  await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+  await expect(page.getByLabel("Sandbox provider")).toBeEnabled();
+  await expect(page.getByLabel("Sandbox provider")).toHaveValue("");
+});
+
+for (const operation of ["setup", "enrollment"] as const) {
+  test(`Core connection changes discard credentials and a late ${operation} result`, async ({ page, request }) => {
+    await page.addInitScript((operation) => {
+      const target = window as Window & { releaseSandboxResponse?: () => void };
+      const originalFetch = window.fetch.bind(window);
+      window.fetch = (input, init) => {
+        const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url, location.href);
+        if (init?.method === "POST" && url.pathname === `/core/v1/sandbox/${operation === "setup" ? "deployment" : "enrollment-tokens"}`) {
+          // Ignore cancellation to check a result accepted before unmounting.
+          return new Promise<Response>((resolve) => {
+            target.releaseSandboxResponse = () => resolve(new Response(JSON.stringify(operation === "setup" ? { installation_id: "old-installation", provider: "docker", core_url: "https://old.example", maintenance: false, owner_epoch: 1 } : { token: "old-secret-token", expires_at: "2026-09-23T09:00:00Z" }), { status: 200 }));
+          });
+        }
+        return originalFetch(input, init);
+      };
+    }, operation);
+    await page.reload();
+    await openSetup(page);
+    if (operation === "setup") {
+      await page.getByLabel("Sandbox provider").selectOption("docker");
+      await page.getByLabel("Core origin reachable from nodes and guests").fill("https://core.example");
+      await page.getByRole("button", { name: "Initialize sandbox deployment" }).click();
+    } else {
+      await request.post(setupUrl, { headers: adminHeaders, data: { provider: "docker", core_url: "https://core.example" } });
+      await page.getByRole("button", { name: "Refresh sandbox state" }).click();
+      await page.getByRole("button", { name: "Generate enrollment command" }).click();
+    }
+    await expect.poll(() => page.evaluate(() => typeof (window as Window & { releaseSandboxResponse?: () => void }).releaseSandboxResponse)).toBe("function");
+    await page.evaluate(() => { location.hash = "system"; });
+    await page.getByRole("button", { name: "Configure Agent Core connection", exact: true }).click();
+    const connection = page.getByRole("dialog", { name: "Connect an Agent Core", exact: true });
+    await connection.getByRole("radio", { name: /Other compatible Core/ }).check();
+    await connection.getByLabel("Compatible Core base URL").fill(`${new URL(page.url()).origin}/v1`);
+    await connection.getByLabel("Bearer token").fill("replacement-token");
+    await connection.getByRole("button", { name: "Apply connection", exact: true }).click();
+    await page.getByRole("button", { name: "Hosted Sandbox Manager", exact: true }).click();
+    await expect(page.getByLabel("Deployment admin key")).toHaveValue("");
+    await page.evaluate(() => { (window as Window & { releaseSandboxResponse?: () => void }).releaseSandboxResponse?.(); });
+    await expect(page.getByLabel("Deployment admin key")).toHaveValue("");
+    await expect(page.getByLabel("One-time enrollment command")).toHaveCount(0);
+    await expect(page.locator(".sandbox-manager")).not.toContainText("old-installation");
+    expect(await page.evaluate(() => JSON.stringify({ local: { ...localStorage }, session: { ...sessionStorage } }))).not.toMatch(/fixture-admin-key|old-secret-token/);
+  });
+}
diff --git a/apps/web/src/features/sandbox/NodeEnrollment.tsx b/apps/web/src/features/sandbox/NodeEnrollment.tsx
new file mode 100644
index 000000000..56f8592cb
--- /dev/null
+++ b/apps/web/src/features/sandbox/NodeEnrollment.tsx
@@ -0,0 +1,31 @@
+import { useState } from "react";
+import type { SandboxDeployment } from "@agents-core-web/agents-client";
+import { sandboxCoreOrigin } from "./core-origin";
+import { enrollmentCommand } from "./enrollment-command";
+
+export function NodeEnrollment({ deployment, initialCoreUrl, busy, enrollment, onEnroll, onClear }: {
+  deployment: SandboxDeployment;
+  initialCoreUrl: string;
+  busy: boolean;
+  enrollment: { token: string; expires_at: string } | null;
+  onEnroll: () => Promise<void>;
+  onClear: () => void;
+}) {
+  const [commandUrl, setCommandUrl] = useState(initialCoreUrl);
+  const coreUrl = sandboxCoreOrigin(deployment.core_url || commandUrl);
+  return <section className="form-stack sandbox-enrollment" aria-labelledby="sandbox-enrollment-heading"><h2 id="sandbox-enrollment-heading">Add node</h2>
+    <ol className="sandbox-steps">
+      <li>Install <code>parsar-sandbox-node</code> from the same Core release on a Linux host. {deployment.provider === "docker" ? "Prepare its local Docker Unix socket and pinned runtime image." : "Prepare KVM access and the qualified microsandbox runtime, helper and firmware."}</li>
+      <li>Create a private <code>/etc/parsar/sandbox-node.json</code> provider configuration with provider <code>{deployment.provider}</code> and installation ID <code>{deployment.installation_id}</code>. Use this host’s own backend paths and image. <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host" target="_blank" rel="noreferrer">Node configuration guide</a></li>
+      <li>Generate the command below. Adjust its absolute paths, node name and capacity, then execute it on that host. Keep its private state directory on persistent storage.</li>
+      <li>Run the node under the host’s service supervisor. Refresh sandbox state here and check that the node is online and its provider is ready.</li>
+    </ol>
+    <label className="field"><span>Core URL reachable from the node</span><input type="url" placeholder="https://core.example" value={deployment.core_url || commandUrl} onChange={(event) => setCommandUrl(event.target.value)} readOnly={Boolean(deployment.core_url)} disabled={busy || Boolean(enrollment)} /></label>
+    <p>This Core origin must also be reachable from sandbox guests. Every added node uses this deployment’s {deployment.provider} provider.</p>
+    {!enrollment ? <button type="button" className="button primary" disabled={busy || !coreUrl} onClick={() => void onEnroll()}>Generate enrollment command</button> : <>
+      <p>One-time enrollment token expires {new Date(enrollment.expires_at).toLocaleString()}. Save the command now; it is cleared when you leave this page.</p>
+      <label className="field"><span>One-time enrollment command</span><textarea readOnly rows={12} value={coreUrl ? enrollmentCommand(enrollment.token, coreUrl) : ""} onFocus={(event) => event.target.select()} spellCheck={false} /></label>
+      <button type="button" className="button" onClick={onClear}>Clear enrollment command</button>
+    </>}
+  </section>;
+}
diff --git a/apps/web/src/features/sandbox/SandboxManagerView.css b/apps/web/src/features/sandbox/SandboxManagerView.css
index 9723d266c..540803d02 100644
--- a/apps/web/src/features/sandbox/SandboxManagerView.css
+++ b/apps/web/src/features/sandbox/SandboxManagerView.css
@@ -21,3 +21,6 @@
 
 .sandbox-diagnostic { max-width: 360px; white-space: normal; line-height: 1.5; margin: 6px 0; }
 .sandbox-diagnostic small { display: block; color: var(--fg-muted); margin-top: 4px; }
+
+.sandbox-steps { margin: 0; padding-left: 22px; color: var(--fg-muted); line-height: 1.6; overflow-wrap: anywhere; }
+.sandbox-steps li + li { margin-top: 10px; }
diff --git a/apps/web/src/features/sandbox/SandboxManagerView.tsx b/apps/web/src/features/sandbox/SandboxManagerView.tsx
index 5dcac3c90..9a3857a7c 100644
--- a/apps/web/src/features/sandbox/SandboxManagerView.tsx
+++ b/apps/web/src/features/sandbox/SandboxManagerView.tsx
@@ -1,10 +1,10 @@
 import { useEffect, useMemo, useRef, useState, type FormEvent } from "react";
-import { SandboxAdminClient, type SandboxAllocation, type SandboxDeployment, type SandboxNode } from "@agents-core-web/agents-client";
-import { isValidDirectCoreBaseUrl } from "../../lib/connection";
+import { SandboxAdminClient, type InitializeSandboxDeployment, type SandboxAllocation, type SandboxDeployment, type SandboxNode } from "@agents-core-web/agents-client";
 import { sandboxAdminBaseUrl } from "./SandboxContext";
 import { SandboxDiagnostic } from "./SandboxDiagnostic";
 import { NodeHealth } from "./NodeHealth";
-import { enrollmentCommand } from "./enrollment-command";
+import { SandboxSetup } from "./SandboxSetup";
+import { NodeEnrollment } from "./NodeEnrollment";
 import "./SandboxManagerView.css";
 
 function message(error: unknown): string {
@@ -12,6 +12,10 @@ function message(error: unknown): string {
 }
 
 export function SandboxManagerView({ coreBaseUrl }: { coreBaseUrl: string }) {
+  return <SandboxAccess key={coreBaseUrl} coreBaseUrl={coreBaseUrl} />;
+}
+
+function SandboxAccess({ coreBaseUrl }: { coreBaseUrl: string }) {
   const [draft, setDraft] = useState("");
   const [credential, setCredential] = useState("");
   function connect(event: FormEvent) {
@@ -40,7 +44,8 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
   const [revision, setRevision] = useState(0);
   const [removeId, setRemoveId] = useState<string | null>(null);
   const [enrollment, setEnrollment] = useState<{ token: string; expires_at: string } | null>(null);
-  const [coreUrl, setCoreUrl] = useState(() => coreBaseUrl.startsWith("http") ? coreBaseUrl.replace(/\/v1\/?$/, "") : "");
+  const initialCoreUrl = coreBaseUrl.startsWith("http") ? coreBaseUrl.replace(/\/v1\/?$/, "") : "";
+  const [setupNeedsRefresh, setSetupNeedsRefresh] = useState(false);
   const lifetime = useRef<AbortController | null>(null);
   useEffect(() => {
     const controller = new AbortController(); lifetime.current = controller;
@@ -52,11 +57,28 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
     void (async () => {
       const [deployment, nodes] = await Promise.all([client.retrieveDeployment({ signal: controller.signal }), client.listNodes({ signal: controller.signal })]);
       const allocations = await Promise.all(nodes.data.map((node) => client.listAllocations(node.id, { signal: controller.signal })));
-      if (!controller.signal.aborted) setSnapshot({ deployment, nodes: nodes.data, allocations: allocations.flatMap((page) => page.data) });
+      if (!controller.signal.aborted) {
+        setSnapshot({ deployment, nodes: nodes.data, allocations: allocations.flatMap((page) => page.data) });
+        setSetupNeedsRefresh(false);
+      }
     })().catch((error) => { if (!controller.signal.aborted) setError(message(error)); })
       .finally(() => { if (!controller.signal.aborted) setLoading(false); });
     return () => controller.abort();
   }, [client, revision]);
+  async function initialize(input: InitializeSandboxDeployment) {
+    const controller = lifetime.current;
+    if (!controller || busy || loading || setupNeedsRefresh) return;
+    setBusy(true); setError(null);
+    try {
+      const deployment = await client.initializeDeployment(input, { signal: controller.signal });
+      if (!controller.signal.aborted) setSnapshot({ deployment, nodes: [], allocations: [] });
+    } catch (error) {
+      if (!controller.signal.aborted) {
+        setSetupNeedsRefresh(true);
+        setError(`${message(error)} Refresh sandbox state to confirm whether setup was saved before submitting again.`);
+      }
+    } finally { if (!controller.signal.aborted) setBusy(false); }
+  }
   async function enroll() {
     const controller = lifetime.current;
     if (!controller || busy) return;
@@ -79,9 +101,10 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
     finally { if (!controller.signal.aborted) setBusy(false); }
   }
   return <div className="form-stack">
-    <div className="sandbox-toolbar"><button type="button" className="button" disabled={loading || busy} onClick={() => setRevision((v) => v + 1)}>Refresh sandbox state</button>{loading ? <span role="status">Loading sandbox state…</span> : null}</div>
+    <div className="sandbox-toolbar"><button type="button" className="button" disabled={loading || busy} onClick={() => setRevision((v) => v + 1)}>Refresh sandbox state</button>{loading ? <span role="status">Loading sandbox state…</span> : busy ? <span role="status">Saving sandbox change…</span> : null}</div>
     {error ? <p role="alert" className="sandbox-error">{error}{snapshot ? " Previously loaded state is shown below." : ""}</p> : null}
-    {snapshot ? <>
+    {snapshot && !snapshot.deployment.provider ? <SandboxSetup key={revision} initialCoreUrl={initialCoreUrl} disabled={busy || loading || setupNeedsRefresh || Boolean(error)} onInitialize={initialize} /> : null}
+    {snapshot?.deployment.provider ? <>
       <dl className="sandbox-summary">
         <div><dt>Provider</dt><dd>{snapshot.deployment.provider === "docker" ? "Docker" : "microsandbox"}</dd></div>
         <div><dt>Maintenance</dt><dd>{snapshot.deployment.maintenance ? "Enabled" : "Off"}</dd></div>
@@ -98,15 +121,7 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
           {snapshot.allocations.map((allocation) => <tr key={allocation.id}><td><code>{allocation.session_id}</code></td><td>{snapshot.nodes.find((node) => node.id === allocation.node_id)?.name ?? allocation.node_id}</td><td>{allocation.state}</td><td>{allocation.compute_phase}</td><td><SandboxDiagnostic diagnostic={allocation.diagnostic} />{!allocation.diagnostic ? "No reported issue" : null}</td></tr>)}
         </tbody></table></div> : <p>No sandbox allocations.</p>}
       </section>
-      <section className="form-stack sandbox-enrollment" aria-labelledby="sandbox-enrollment-heading"><h2 id="sandbox-enrollment-heading">Add node</h2>
-        <p>Install parsar-sandbox-node and prepare its {snapshot.deployment.provider} provider configuration on the target host. Adjust the absolute paths, node name and capacity in the command before running it.</p>
-        <label className="field"><span>Core URL reachable from the node</span><input type="url" placeholder="https://core.example" value={coreUrl} onChange={(event) => setCoreUrl(event.target.value)} disabled={busy || Boolean(enrollment)} /></label>
-        {!enrollment ? <button type="button" className="button primary" disabled={busy || !isValidDirectCoreBaseUrl(coreUrl)} onClick={() => void enroll()}>Generate enrollment command</button> : <>
-          <p>One-time enrollment token expires {new Date(enrollment.expires_at).toLocaleString()}. Save the command now; it is cleared when you leave this page.</p>
-          <label className="field"><span>One-time enrollment command</span><textarea readOnly rows={12} value={enrollmentCommand(enrollment.token, coreUrl.trim())} onFocus={(event) => event.target.select()} spellCheck={false} /></label>
-          <button type="button" className="button" onClick={() => setEnrollment(null)}>Clear enrollment command</button>
-        </>}
-      </section>
+      <NodeEnrollment deployment={snapshot.deployment} initialCoreUrl={initialCoreUrl} busy={busy || loading || Boolean(error)} enrollment={enrollment} onEnroll={enroll} onClear={() => setEnrollment(null)} />
     </> : null}
   </div>;
 }
diff --git a/apps/web/src/features/sandbox/SandboxSetup.tsx b/apps/web/src/features/sandbox/SandboxSetup.tsx
new file mode 100644
index 000000000..a5af3a7a8
--- /dev/null
+++ b/apps/web/src/features/sandbox/SandboxSetup.tsx
@@ -0,0 +1,30 @@
+import { useState, type FormEvent } from "react";
+import type { InitializeSandboxDeployment, SandboxProvider } from "@agents-core-web/agents-client";
+import { sandboxCoreOrigin } from "./core-origin";
+
+export function SandboxSetup({ initialCoreUrl, disabled, onInitialize }: {
+  initialCoreUrl: string;
+  disabled: boolean;
+  onInitialize: (input: InitializeSandboxDeployment) => Promise<void>;
+}) {
+  const [provider, setProvider] = useState<SandboxProvider | "">("");
+  const [coreUrl, setCoreUrl] = useState(initialCoreUrl);
+  const origin = sandboxCoreOrigin(coreUrl);
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    if (provider && origin && !disabled) void onInitialize({ provider, core_url: origin });
+  }
+  return <form className="form-stack sandbox-enrollment" onSubmit={submit} aria-labelledby="sandbox-setup-heading">
+    <h2 id="sandbox-setup-heading">Set up hosted sandboxes</h2>
+    <p>Core is running with no sandbox nodes. Choose one provider for this deployment; every node you add must use it. This choice cannot be changed here.</p>
+    <label className="field"><span>Sandbox provider</span><select value={provider} onChange={(event) => setProvider(event.target.value as SandboxProvider)} disabled={disabled} required>
+      <option value="" disabled>Choose a provider</option><option value="docker">Docker</option><option value="microsandbox">microsandbox</option>
+    </select></label>
+    <p>{provider === "docker" ? "Docker nodes need a local Docker Unix socket and a pinned runtime image." : provider === "microsandbox" ? "microsandbox nodes need Linux with KVM, the qualified runtime, helper and firmware." : "Prepare a compatible host after selecting the provider."}</p>
+    <label className="field"><span>Core origin reachable from nodes and guests</span><input type="url" value={coreUrl} onChange={(event) => setCoreUrl(event.target.value)} placeholder="https://core.example" disabled={disabled} required aria-describedby="sandbox-core-origin-help" /></label>
+    <p id="sandbox-core-origin-help">Use the Core API origin, reachable from every node and sandbox guest, without a path or credentials. Remote hosts require HTTPS; loopback HTTP is for local use only. The console URL may be different.</p>
+    {coreUrl && !origin ? <p className="sandbox-error">Enter an HTTPS origin such as https://core.example, or a loopback HTTP origin for local use.</p> : null}
+    <button className="button primary" type="submit" disabled={disabled || !provider || !origin}>Initialize sandbox deployment</button>
+    <p>Next, generate an enrollment command and run it on your prepared host. Initializing does not install a runtime or create a node.</p>
+  </form>;
+}
diff --git a/apps/web/src/features/sandbox/core-origin.test.ts b/apps/web/src/features/sandbox/core-origin.test.ts
new file mode 100644
index 000000000..334a1a836
--- /dev/null
+++ b/apps/web/src/features/sandbox/core-origin.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { sandboxCoreOrigin } from "./core-origin";
+
+describe("sandbox deployment Core origin", () => {
+  it.each([
+    [" https://CORE.example:8443/ ", "https://core.example:8443"],
+    ["http://localhost:8080", "http://localhost:8080"],
+    ["http://127.0.0.2:8080/", "http://127.0.0.2:8080"],
+    ["http://[::1]:8080", "http://[::1]:8080"],
+  ])("normalizes %s", (input, expected) => expect(sandboxCoreOrigin(input)).toBe(expected));
+  it.each(["", "/v1", "http://remote.example", "http://host.localhost", "https://core.example/v1", "https://core.example/path/..", "https://user:secret@core.example", "https://@core.example", "https://core.example?", "https://core.example#", "https://core.example//", "https://core.example\\path", "https://co\nre.example", "file://core.example"])("rejects unsafe or non-origin input %s", (input) => expect(sandboxCoreOrigin(input)).toBeNull());
+});
diff --git a/apps/web/src/features/sandbox/core-origin.ts b/apps/web/src/features/sandbox/core-origin.ts
new file mode 100644
index 000000000..c2d84dce4
--- /dev/null
+++ b/apps/web/src/features/sandbox/core-origin.ts
@@ -0,0 +1,9 @@
+import { isValidDirectCoreBaseUrl } from "../../lib/connection";
+
+export function sandboxCoreOrigin(value: string): string | null {
+  const candidate = value.trim();
+  if (!/^https?:\/\/[^/?#\\\s]+\/?$/i.test(candidate) || !isValidDirectCoreBaseUrl(candidate)) return null;
+  const url = new URL(candidate);
+  if (url.protocol === "http:" && url.hostname.endsWith(".localhost")) return null;
+  return url.origin;
+}
diff --git a/packages/agents-client/src/sandbox-client.test.ts b/packages/agents-client/src/sandbox-client.test.ts
index 11b58cf6f..ac0f6254b 100644
--- a/packages/agents-client/src/sandbox-client.test.ts
+++ b/packages/agents-client/src/sandbox-client.test.ts
@@ -4,6 +4,32 @@ import { SandboxAdminClient, SandboxProjectClient } from "./sandbox-client";
 function response(value: unknown, status = 200) { return new Response(JSON.stringify(value), { status }); }
 
 describe("Core sandbox credential boundaries", () => {
+  it("initializes using only the explicit provider and origin with cancellation and admin credentials", async () => {
+    const deployment = { installation_id: "installation", provider: "docker", core_url: "https://core.example", maintenance: false, owner_epoch: 1 };
+    const fetch = vi.fn<typeof globalThis.fetch>().mockResolvedValue(response(deployment));
+    const admin = new SandboxAdminClient({ baseUrl: "/core/v1/sandbox", token: "admin-only", fetch });
+    const controller = new AbortController();
+    expect(await admin.initializeDeployment({ provider: "docker", core_url: "https://core.example" }, { signal: controller.signal })).toEqual(deployment);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(url).toBe("/core/v1/sandbox/deployment");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(String(init?.body))).toEqual({ provider: "docker", core_url: "https://core.example" });
+    expect(init?.signal).toBe(controller.signal);
+    expect(new Headers(init?.headers).get("Authorization")).toBe("Bearer admin-only");
+    expect(new Headers(init?.headers).has("OpenAI-Beta")).toBe(false);
+  });
+  it.each([409, 503])("does not retry initialization after HTTP %s", async (status) => {
+    const fetch = vi.fn<typeof globalThis.fetch>().mockResolvedValue(response({ error: { message: "Setup failed", code: "sandbox_deployment_conflict" } }, status));
+    const admin = new SandboxAdminClient({ baseUrl: "/core/v1/sandbox", token: "admin", fetch });
+    await expect(admin.initializeDeployment({ provider: "microsandbox", core_url: "https://core.example" })).rejects.toThrow("Setup failed");
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+  it("does not retry an uncertain initialization transport failure", async () => {
+    const fetch = vi.fn<typeof globalThis.fetch>().mockRejectedValue(new TypeError("Connection lost"));
+    const admin = new SandboxAdminClient({ baseUrl: "/core/v1/sandbox", token: "admin", fetch });
+    await expect(admin.initializeDeployment({ provider: "docker", core_url: "https://core.example" })).rejects.toThrow("Connection lost");
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
   it("uses the explicit admin credential and admin routes without a project beta header", async () => {
     const fetch = vi.fn<typeof globalThis.fetch>().mockImplementation(async () => response({ data: [] }));
     const admin = new SandboxAdminClient({ baseUrl: "https://core.example/core/v1/sandbox", token: "admin-only", fetch });
diff --git a/packages/agents-client/src/sandbox-client.ts b/packages/agents-client/src/sandbox-client.ts
index ba7c929c3..fe324b910 100644
--- a/packages/agents-client/src/sandbox-client.ts
+++ b/packages/agents-client/src/sandbox-client.ts
@@ -3,9 +3,13 @@ import type { ReadOptions } from "./types";
 
 export type SandboxDiagnostic = "" | "node_unavailable" | "resource_missing" | "compute_unconfirmed" | "ownership_mismatch" | "provider_unavailable";
 
+export type SandboxProvider = "docker" | "microsandbox";
+export interface InitializeSandboxDeployment { provider: SandboxProvider; core_url: string }
+
 export interface SandboxDeployment {
   installation_id: string;
-  provider: "docker" | "microsandbox";
+  provider: SandboxProvider | "";
+  core_url: string;
   maintenance: boolean;
   owner_epoch: number;
 }
@@ -65,6 +69,9 @@ export class SandboxAdminClient extends OpenAIAgentsClient {
   retrieveDeployment(options?: ReadOptions): Promise<SandboxDeployment> {
     return this.request("/deployment", { signal: options?.signal }, undefined, false);
   }
+  initializeDeployment(input: InitializeSandboxDeployment, options?: ReadOptions): Promise<SandboxDeployment> {
+    return this.request("/deployment", { method: "POST", body: JSON.stringify(input), signal: options?.signal }, undefined, false);
+  }
   listNodes(options?: ReadOptions): Promise<{ data: SandboxNode[] }> {
     return this.request("/nodes", { signal: options?.signal }, undefined, false);
   }

From f0714756853fd279fdda2f263faa3c4c4ca7be2c Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:39:04 +0800
Subject: [PATCH 2/9] Initialize sandbox deployment from Web without restarting
 execution

---
 services/agents-api/internal/api/errors.go    |   2 +
 services/agents-api/internal/api/handler.go   |   1 +
 .../internal/api/sandbox_deployment_setup.go  |  44 +++++
 .../api/sandbox_deployment_setup_test.go      |  58 +++++++
 .../internal/api/sandbox_manager.go           |   1 +
 .../db/queries/sandbox_deployment_setup.sql   |   7 +
 .../agents-api/internal/db/sqlc/models.go     |   4 +
 .../db/sqlc/runtime_deployment.sql.go         |   6 +-
 .../internal/db/sqlc/runtime_nodes.sql.go     |   6 +-
 .../db/sqlc/sandbox_deployment_setup.sql.go   |  46 +++++
 .../execution/environment_admission.go        |  13 +-
 .../internal/execution/runtime_lifecycle.go   |  35 +++-
 .../internal/execution/runtime_manager.go     |  31 ++--
 .../execution/sandbox_deployment_setup.go     |  65 +++++++
 .../sandbox_deployment_setup_test.go          |  84 +++++++++
 .../agents-api/internal/execution/worker.go   |  12 +-
 .../internal/store/runtime_deployment.go      |   3 +
 .../internal/store/runtime_node_types.go      |   1 +
 .../internal/store/runtime_nodes.go           |   2 +-
 .../internal/store/runtime_placements.go      |   2 +-
 .../store/sandbox_deployment_setup.go         | 163 ++++++++++++++++++
 .../store/sandbox_deployment_setup_test.go    | 147 ++++++++++++++++
 .../store/sandbox_deployment_worker_test.go   |  88 ++++++++++
 .../000058_sandbox_deployment_setup.sql       |  38 ++++
 24 files changed, 833 insertions(+), 26 deletions(-)
 create mode 100644 services/agents-api/internal/api/sandbox_deployment_setup.go
 create mode 100644 services/agents-api/internal/api/sandbox_deployment_setup_test.go
 create mode 100644 services/agents-api/internal/db/queries/sandbox_deployment_setup.sql
 create mode 100644 services/agents-api/internal/db/sqlc/sandbox_deployment_setup.sql.go
 create mode 100644 services/agents-api/internal/execution/sandbox_deployment_setup.go
 create mode 100644 services/agents-api/internal/execution/sandbox_deployment_setup_test.go
 create mode 100644 services/agents-api/internal/store/sandbox_deployment_setup.go
 create mode 100644 services/agents-api/internal/store/sandbox_deployment_setup_test.go
 create mode 100644 services/agents-api/internal/store/sandbox_deployment_worker_test.go
 create mode 100644 services/agents-api/migrations/000058_sandbox_deployment_setup.sql

diff --git a/services/agents-api/internal/api/errors.go b/services/agents-api/internal/api/errors.go
index 46e3bafb4..c2c8fd08e 100644
--- a/services/agents-api/internal/api/errors.go
+++ b/services/agents-api/internal/api/errors.go
@@ -66,6 +66,8 @@ func writeFieldError(w http.ResponseWriter, err error) bool {
 
 func writeStoreError(w http.ResponseWriter, r *http.Request, err error, notFoundParam ...string) {
 	switch {
+	case errors.Is(err, store.ErrSandboxDeploymentConflict):
+		writeError(w, http.StatusConflict, "sandbox_deployment_conflict", "The sandbox deployment is already configured or is managed by a deployment file.")
 	case errors.Is(err, store.ErrRuntimeNodeCredential):
 		writeError(w, http.StatusUnauthorized, "invalid_node_credential", "A valid sandbox node enrollment or node credential is required.")
 	case errors.Is(err, store.ErrRuntimeNodeInUse):
diff --git a/services/agents-api/internal/api/handler.go b/services/agents-api/internal/api/handler.go
index 958017bce..f5b2de16f 100644
--- a/services/agents-api/internal/api/handler.go
+++ b/services/agents-api/internal/api/handler.go
@@ -38,6 +38,7 @@ type ResourceStore interface {
 type Handler struct {
 	sandboxStore        *store.Store
 	deploymentAuth      *DeploymentAuthenticator
+	sandboxSetup        func(context.Context, store.SandboxDeploymentSetupRequest) (store.RuntimeDeploymentView, error)
 	policy              execution.Policy
 	store               ResourceStore
 	auth                *Authenticator
diff --git a/services/agents-api/internal/api/sandbox_deployment_setup.go b/services/agents-api/internal/api/sandbox_deployment_setup.go
new file mode 100644
index 000000000..3767943f0
--- /dev/null
+++ b/services/agents-api/internal/api/sandbox_deployment_setup.go
@@ -0,0 +1,44 @@
+package api
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+)
+
+func WithSandboxDeploymentSetup(initialize func(context.Context, store.SandboxDeploymentSetupRequest) (store.RuntimeDeploymentView, error)) Option {
+	return func(h *Handler) { h.sandboxSetup = initialize }
+}
+
+// @Summary Initialize the deployment sandbox provider once
+// @Description Selects one immutable provider and public Core origin. Exact retries return the existing selection; differing selections and file-managed deployments reject. This does not create a node or execute work.
+// @Tags Sandbox Manager
+// @Produce json
+// @Security DeploymentAdminAuth
+// @Accept json
+// @Param body body store.SandboxDeploymentSetupRequest true "Deployment selection"
+// @Success 200 {object} store.RuntimeDeploymentView
+// @Failure 400,401,409,500,503 {object} v1.ErrorResponse
+// @Router /core/v1/sandbox/deployment [post]
+func (h *Handler) initializeSandboxDeployment(w http.ResponseWriter, r *http.Request) {
+	raw, ok := readJSONBody(w, r)
+	if !ok {
+		return
+	}
+	var input store.SandboxDeploymentSetupRequest
+	if decodeInputObject(raw, &input, "provider", "core_url") != nil {
+		writeStoreError(w, r, store.ErrInvalidInput)
+		return
+	}
+	if h.sandboxSetup == nil {
+		writeStoreError(w, r, store.ErrSandboxDeploymentConflict)
+		return
+	}
+	result, err := h.sandboxSetup(r.Context(), input)
+	if err != nil {
+		writeStoreError(w, r, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, result)
+}
diff --git a/services/agents-api/internal/api/sandbox_deployment_setup_test.go b/services/agents-api/internal/api/sandbox_deployment_setup_test.go
new file mode 100644
index 000000000..e8aa4e14e
--- /dev/null
+++ b/services/agents-api/internal/api/sandbox_deployment_setup_test.go
@@ -0,0 +1,58 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/MiniMax-AI-Dev/parsar/internal/agentdaemon/device"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+)
+
+func TestSandboxDeploymentSetupRequiresAdministratorAndStrictBody(t *testing.T) {
+	project, _ := NewAuthenticator([]APIKey{callerBinding()})
+	admin, _ := NewDeploymentAuthenticator([]string{device.HashCredential("administrator")})
+	calls := 0
+	initialize := func(_ context.Context, input store.SandboxDeploymentSetupRequest) (store.RuntimeDeploymentView, error) {
+		calls++
+		if input.Provider == "microsandbox" {
+			return store.RuntimeDeploymentView{}, store.ErrSandboxDeploymentConflict
+		}
+		return store.RuntimeDeploymentView{Provider: input.Provider, CoreURL: input.CoreURL}, nil
+	}
+	h, err := NewHandler(&recordingStore{}, project, "codex", WithSandboxManager(&store.Store{}, admin), WithSandboxDeploymentSetup(initialize))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		token, body   string
+		status, calls int
+	}{
+		{"caller", `{"provider":"docker","core_url":"https://core.example"}`, 401, 0},
+		{"node-credential", `{"provider":"docker","core_url":"https://core.example"}`, 401, 0},
+		{"enrollment-token", `{"provider":"docker","core_url":"https://core.example"}`, 401, 0},
+		{"administrator", `{"provider":"docker","core_url":"https://core.example","unexpected":true}`, 400, 0},
+		{"administrator", `{"provider":"docker","core_url":"https://core.example"}`, 200, 1},
+		{"administrator", `{"provider":"microsandbox","core_url":"https://core.example"}`, 409, 2},
+	} {
+		request := httptest.NewRequest(http.MethodPost, "/core/v1/sandbox/deployment", strings.NewReader(test.body))
+		request.Header.Set("Authorization", "Bearer "+test.token)
+		result := httptest.NewRecorder()
+		h.ServeHTTP(result, request)
+		if result.Code != test.status || calls != test.calls {
+			t.Fatal(result.Code, calls, result.Body.String())
+		}
+	}
+}
+
+func TestSandboxDeploymentSetupFileModeReturnsConflict(t *testing.T) {
+	h := &Handler{}
+	request := httptest.NewRequest(http.MethodPost, "/core/v1/sandbox/deployment", strings.NewReader(`{"provider":"docker","core_url":"https://core.example"}`))
+	result := httptest.NewRecorder()
+	h.initializeSandboxDeployment(result, request)
+	if result.Code != http.StatusConflict || !strings.Contains(result.Body.String(), "sandbox_deployment_conflict") {
+		t.Fatal(result.Code, result.Body.String())
+	}
+}
diff --git a/services/agents-api/internal/api/sandbox_manager.go b/services/agents-api/internal/api/sandbox_manager.go
index a6827fa31..90e832054 100644
--- a/services/agents-api/internal/api/sandbox_manager.go
+++ b/services/agents-api/internal/api/sandbox_manager.go
@@ -40,6 +40,7 @@ func (h *Handler) registerSandboxManagerRoutes(r chi.Router) {
 	r.Route("/core/v1/sandbox", func(r chi.Router) {
 		r.Use(h.deploymentAuth.authenticate)
 		r.Get("/deployment", h.sandboxDeployment)
+		r.Post("/deployment", h.initializeSandboxDeployment)
 		r.Get("/nodes", h.sandboxNodes)
 		r.Patch("/nodes/{node_id}", h.updateSandboxNode)
 		r.Delete("/nodes/{node_id}", h.removeSandboxNode)
diff --git a/services/agents-api/internal/db/queries/sandbox_deployment_setup.sql b/services/agents-api/internal/db/queries/sandbox_deployment_setup.sql
new file mode 100644
index 000000000..fe85ba126
--- /dev/null
+++ b/services/agents-api/internal/db/queries/sandbox_deployment_setup.sql
@@ -0,0 +1,7 @@
+-- name: ClaimWebSandboxDeployment :exec
+UPDATE runtime_deployment SET installation_id=$1, web_managed=true,
+owner_epoch=owner_epoch+1, updated_at=clock_timestamp() WHERE singleton=true;
+
+-- name: InitializeSandboxDeployment :exec
+UPDATE runtime_deployment SET provider_kind=$1, core_url=$2, backend_fingerprint=$3,
+idle_seconds=$4, retention_seconds=$5, updated_at=clock_timestamp() WHERE singleton=true;
diff --git a/services/agents-api/internal/db/sqlc/models.go b/services/agents-api/internal/db/sqlc/models.go
index dbdd5d352..190ca6ab7 100644
--- a/services/agents-api/internal/db/sqlc/models.go
+++ b/services/agents-api/internal/db/sqlc/models.go
@@ -172,6 +172,10 @@ type RuntimeDeployment struct {
 	ProviderKind       string             `json:"provider_kind"`
 	LocalNodeID        pgtype.UUID        `json:"local_node_id"`
 	OwnerEpoch         int64              `json:"owner_epoch"`
+	WebManaged         bool               `json:"web_managed"`
+	CoreUrl            string             `json:"core_url"`
+	IdleSeconds        int64              `json:"idle_seconds"`
+	RetentionSeconds   int64              `json:"retention_seconds"`
 }
 
 type RuntimeDeviceAuthority struct {
diff --git a/services/agents-api/internal/db/sqlc/runtime_deployment.sql.go b/services/agents-api/internal/db/sqlc/runtime_deployment.sql.go
index 9322138b2..4572cc053 100644
--- a/services/agents-api/internal/db/sqlc/runtime_deployment.sql.go
+++ b/services/agents-api/internal/db/sqlc/runtime_deployment.sql.go
@@ -33,7 +33,7 @@ func (q *Queries) CountRuntimeDeploymentResources(ctx context.Context) (CountRun
 }
 
 const lockRuntimeDeployment = `-- name: LockRuntimeDeployment :one
-SELECT singleton, installation_id, backend_fingerprint, maintenance, updated_at, provider_kind, local_node_id, owner_epoch FROM runtime_deployment WHERE singleton = true FOR UPDATE
+SELECT singleton, installation_id, backend_fingerprint, maintenance, updated_at, provider_kind, local_node_id, owner_epoch, web_managed, core_url, idle_seconds, retention_seconds FROM runtime_deployment WHERE singleton = true FOR UPDATE
 `
 
 func (q *Queries) LockRuntimeDeployment(ctx context.Context) (RuntimeDeployment, error) {
@@ -48,6 +48,10 @@ func (q *Queries) LockRuntimeDeployment(ctx context.Context) (RuntimeDeployment,
 		&i.ProviderKind,
 		&i.LocalNodeID,
 		&i.OwnerEpoch,
+		&i.WebManaged,
+		&i.CoreUrl,
+		&i.IdleSeconds,
+		&i.RetentionSeconds,
 	)
 	return i, err
 }
diff --git a/services/agents-api/internal/db/sqlc/runtime_nodes.sql.go b/services/agents-api/internal/db/sqlc/runtime_nodes.sql.go
index 82bdc5106..bf388f0e0 100644
--- a/services/agents-api/internal/db/sqlc/runtime_nodes.sql.go
+++ b/services/agents-api/internal/db/sqlc/runtime_nodes.sql.go
@@ -153,7 +153,7 @@ func (q *Queries) DisconnectRuntimeNode(ctx context.Context, arg DisconnectRunti
 }
 
 const getRuntimeDeployment = `-- name: GetRuntimeDeployment :one
-SELECT singleton, installation_id, backend_fingerprint, maintenance, updated_at, provider_kind, local_node_id, owner_epoch FROM runtime_deployment WHERE singleton=true
+SELECT singleton, installation_id, backend_fingerprint, maintenance, updated_at, provider_kind, local_node_id, owner_epoch, web_managed, core_url, idle_seconds, retention_seconds FROM runtime_deployment WHERE singleton=true
 `
 
 func (q *Queries) GetRuntimeDeployment(ctx context.Context) (RuntimeDeployment, error) {
@@ -168,6 +168,10 @@ func (q *Queries) GetRuntimeDeployment(ctx context.Context) (RuntimeDeployment,
 		&i.ProviderKind,
 		&i.LocalNodeID,
 		&i.OwnerEpoch,
+		&i.WebManaged,
+		&i.CoreUrl,
+		&i.IdleSeconds,
+		&i.RetentionSeconds,
 	)
 	return i, err
 }
diff --git a/services/agents-api/internal/db/sqlc/sandbox_deployment_setup.sql.go b/services/agents-api/internal/db/sqlc/sandbox_deployment_setup.sql.go
new file mode 100644
index 000000000..5603b17f7
--- /dev/null
+++ b/services/agents-api/internal/db/sqlc/sandbox_deployment_setup.sql.go
@@ -0,0 +1,46 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.29.0
+// source: sandbox_deployment_setup.sql
+
+package sqlc
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const claimWebSandboxDeployment = `-- name: ClaimWebSandboxDeployment :exec
+UPDATE runtime_deployment SET installation_id=$1, web_managed=true,
+owner_epoch=owner_epoch+1, updated_at=clock_timestamp() WHERE singleton=true
+`
+
+func (q *Queries) ClaimWebSandboxDeployment(ctx context.Context, installationID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, claimWebSandboxDeployment, installationID)
+	return err
+}
+
+const initializeSandboxDeployment = `-- name: InitializeSandboxDeployment :exec
+UPDATE runtime_deployment SET provider_kind=$1, core_url=$2, backend_fingerprint=$3,
+idle_seconds=$4, retention_seconds=$5, updated_at=clock_timestamp() WHERE singleton=true
+`
+
+type InitializeSandboxDeploymentParams struct {
+	ProviderKind       string `json:"provider_kind"`
+	CoreUrl            string `json:"core_url"`
+	BackendFingerprint string `json:"backend_fingerprint"`
+	IdleSeconds        int64  `json:"idle_seconds"`
+	RetentionSeconds   int64  `json:"retention_seconds"`
+}
+
+func (q *Queries) InitializeSandboxDeployment(ctx context.Context, arg InitializeSandboxDeploymentParams) error {
+	_, err := q.db.Exec(ctx, initializeSandboxDeployment,
+		arg.ProviderKind,
+		arg.CoreUrl,
+		arg.BackendFingerprint,
+		arg.IdleSeconds,
+		arg.RetentionSeconds,
+	)
+	return err
+}
diff --git a/services/agents-api/internal/execution/environment_admission.go b/services/agents-api/internal/execution/environment_admission.go
index 2a712aca3..a0ee51c96 100644
--- a/services/agents-api/internal/execution/environment_admission.go
+++ b/services/agents-api/internal/execution/environment_admission.go
@@ -22,7 +22,7 @@ func preparedEnvironmentConfiguration(configuration json.RawMessage) bool {
 		(snapshot.Environment.Type == "self_hosted" || snapshot.Environment.Type == "openai_hosted")
 }
 
-func (w *Worker) validateEnvironmentAdmission(engine string, configuration json.RawMessage) error {
+func (w *Worker) validateEnvironmentAdmission(ctx context.Context, engine string, configuration json.RawMessage) error {
 	var snapshot Snapshot
 	if json.Unmarshal(configuration, &snapshot) != nil || snapshot.Environment == nil {
 		return store.ErrInvalidInput
@@ -36,6 +36,13 @@ func (w *Worker) validateEnvironmentAdmission(engine string, configuration json.
 		if w.runtimes == nil {
 			return ErrExecutionUnavailable
 		}
+		ready, err := w.runtimes.ensureDeployment(ctx)
+		if err != nil {
+			return err
+		}
+		if !ready {
+			return ErrExecutionUnavailable
+		}
 	default:
 		return store.ErrInvalidInput
 	}
@@ -47,7 +54,7 @@ func (w *Worker) validateCreation(ctx context.Context, input store.CreateSession
 		return err
 	}
 	if preparedEnvironmentConfiguration(input.Configuration) {
-		if err := w.validateEnvironmentAdmission(input.Engine, input.Configuration); err != nil {
+		if err := w.validateEnvironmentAdmission(ctx, input.Engine, input.Configuration); err != nil {
 			return err
 		}
 		var snapshot Snapshot
@@ -66,7 +73,7 @@ func (w *Worker) validateCreation(ctx context.Context, input store.CreateSession
 }
 
 func (w *Worker) submitEnvironmentInputs(ctx context.Context, session store.Session, key string, inputs []store.Input) ([]store.InputReceipt, error) {
-	if err := w.validateEnvironmentAdmission(session.Engine, session.Configuration); err != nil {
+	if err := w.validateEnvironmentAdmission(ctx, session.Engine, session.Configuration); err != nil {
 		return nil, err
 	}
 	if err := w.checkAdmissionOwnership(ctx); err != nil {
diff --git a/services/agents-api/internal/execution/runtime_lifecycle.go b/services/agents-api/internal/execution/runtime_lifecycle.go
index 51169b357..a1599dcb1 100644
--- a/services/agents-api/internal/execution/runtime_lifecycle.go
+++ b/services/agents-api/internal/execution/runtime_lifecycle.go
@@ -20,6 +20,7 @@ import (
 // RuntimeProvider binds one deployment to one sandbox installation.
 // BackendFingerprint identifies its namespace independently of mutable sizing.
 type RuntimeProvider struct {
+	loadDeployment                   func(context.Context) (*RuntimeProvider, error)
 	VerifyLegacyOwnership            store.RuntimeOwnershipVerifier
 	ProviderKind                     string
 	LocalNodeID                      string
@@ -52,25 +53,42 @@ func newRuntimeManager(s *store.Store, registry *gateway.Registry, config *Runti
 	if config == nil {
 		return nil, nil
 	}
+	var copied RuntimeProvider
+	if config.loadDeployment != nil {
+		id, err := uuid.Parse(config.InstallationID)
+		if err != nil || id == uuid.Nil || id.String() != config.InstallationID || registry == nil {
+			return nil, sandbox.ErrInvalid
+		}
+	} else {
+		var err error
+		copied, err = validatedRuntimeProvider(config, registry)
+		if err != nil {
+			return nil, err
+		}
+	}
+	ctx, stop := context.WithCancel(context.Background())
+	return &runtimeManager{store: s, registry: registry, config: copied, setupInstallationID: config.InstallationID, loadDeployment: config.loadDeployment, setupGate: make(chan struct{}, 1), ctx: ctx, cancel: stop, nodes: make(map[string]*runtimeNode), failed: make(chan error, 1), inventory: make(chan struct{}, 1)}, nil
+}
+
+func validatedRuntimeProvider(config *RuntimeProvider, registry *gateway.Registry) (RuntimeProvider, error) {
 	u, err := url.Parse(config.CoreURL)
 	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") || u.User != nil || u.RawQuery != "" || u.Fragment != "" || config.Provider == nil || registry == nil {
-		return nil, sandbox.ErrInvalid
+		return RuntimeProvider{}, sandbox.ErrInvalid
 	}
 	id, err := uuid.Parse(config.InstallationID)
 	fingerprint, fingerprintErr := hex.DecodeString(config.BackendFingerprint)
 	if err != nil || id == uuid.Nil || id.String() != config.InstallationID || fingerprintErr != nil || len(fingerprint) != 32 || hex.EncodeToString(fingerprint) != config.BackendFingerprint {
-		return nil, sandbox.ErrInvalid
+		return RuntimeProvider{}, sandbox.ErrInvalid
 	}
 	copied := *config
 	if config.Suspension != nil {
 		policy := *config.Suspension
 		if _, ok := config.Provider.(sandbox.CheckpointProvider); !ok || policy.IdleTimeout < time.Second || policy.Retention < time.Second || policy.MaxActive < 1 || policy.MaxRetained < policy.MaxActive {
-			return nil, sandbox.ErrInvalid
+			return RuntimeProvider{}, sandbox.ErrInvalid
 		}
 		copied.Suspension = &policy
 	}
-	ctx, stop := context.WithCancel(context.Background())
-	return &runtimeManager{store: s, registry: registry, config: copied, ctx: ctx, cancel: stop, nodes: make(map[string]*runtimeNode), failed: make(chan error, 1), inventory: make(chan struct{}, 1)}, nil
+	return copied, nil
 }
 
 func (r *runtimeLifecycle) lock(ctx context.Context) error {
@@ -105,6 +123,13 @@ func (w *Worker) ProvisionEnvironment(ctx context.Context, tenant, environment,
 		return store.RuntimeAllocation{}, err
 	}
 	defer finish()
+	ready, err := w.runtimes.ensureDeployment(ctx)
+	if err != nil {
+		return store.RuntimeAllocation{}, err
+	}
+	if !ready {
+		return store.RuntimeAllocation{}, ErrExecutionUnavailable
+	}
 	nodeID, err := w.runtimes.store.ResolveRuntimeLifecycleNode(ctx, tenant, environment)
 	if err != nil {
 		return store.RuntimeAllocation{}, err
diff --git a/services/agents-api/internal/execution/runtime_manager.go b/services/agents-api/internal/execution/runtime_manager.go
index 6d81e2b77..271e03a79 100644
--- a/services/agents-api/internal/execution/runtime_manager.go
+++ b/services/agents-api/internal/execution/runtime_manager.go
@@ -12,17 +12,20 @@ import (
 // runtimeManager owns node membership, not provider operations. Each registered
 // node has one serial lifecycle; slow provider work cannot occupy another node.
 type runtimeManager struct {
-	store           *store.Store
-	registry        *gateway.Registry
-	config          RuntimeProvider
-	ctx             context.Context
-	cancel          context.CancelFunc
-	mu              sync.Mutex
-	nodes           map[string]*runtimeNode
-	running, closed bool
-	active          sync.WaitGroup
-	failed          chan error
-	inventory       chan struct{}
+	store               *store.Store
+	registry            *gateway.Registry
+	config              RuntimeProvider
+	setupInstallationID string
+	loadDeployment      func(context.Context) (*RuntimeProvider, error)
+	setupGate           chan struct{}
+	ctx                 context.Context
+	cancel              context.CancelFunc
+	mu                  sync.Mutex
+	nodes               map[string]*runtimeNode
+	running, closed     bool
+	active              sync.WaitGroup
+	failed              chan error
+	inventory           chan struct{}
 }
 
 type runtimeNode struct {
@@ -51,7 +54,7 @@ func (m *runtimeManager) enter(parent context.Context) (context.Context, func(),
 
 func (m *runtimeManager) node(id string) (*runtimeNode, error) {
 	m.mu.Lock()
-	if m.closed || (id == "") != (m.config.ProviderKind == "") {
+	if m.closed || (m.loadDeployment != nil && m.config.Provider == nil) || (id == "") != (m.config.ProviderKind == "") {
 		m.mu.Unlock()
 		return nil, ErrExecutionUnavailable
 	}
@@ -94,6 +97,10 @@ func (m *runtimeManager) hints(id string) chan<- struct{} {
 }
 
 func (m *runtimeManager) syncNodes(ctx context.Context) ([]*runtimeNode, error) {
+	ready, err := m.ensureDeployment(ctx)
+	if err != nil || !ready {
+		return nil, err
+	}
 	select {
 	case m.inventory <- struct{}{}:
 	case <-ctx.Done():
diff --git a/services/agents-api/internal/execution/sandbox_deployment_setup.go b/services/agents-api/internal/execution/sandbox_deployment_setup.go
new file mode 100644
index 000000000..70fae6f1a
--- /dev/null
+++ b/services/agents-api/internal/execution/sandbox_deployment_setup.go
@@ -0,0 +1,65 @@
+package execution
+
+import (
+	"context"
+
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+)
+
+// NewDeferredRuntimeProvider enables Web setup for one fixed installation. The
+// loader returns nil until selection, then an immutable remote-node provider.
+// This is one-time activation, not provider replacement or configuration reload.
+func NewDeferredRuntimeProvider(installationID string, load func(context.Context) (*RuntimeProvider, error)) *RuntimeProvider {
+	return &RuntimeProvider{InstallationID: installationID, loadDeployment: load}
+}
+
+func (w *Worker) InitializeSandboxDeployment(ctx context.Context, input store.SandboxDeploymentSetupRequest) (store.RuntimeDeploymentView, error) {
+	if w.runtimes == nil || w.runtimes.loadDeployment == nil {
+		return store.RuntimeDeploymentView{}, store.ErrSandboxDeploymentConflict
+	}
+	return w.dispatcher.Store.InitializeSandboxDeployment(ctx, w.runtimes.setupInstallationID, input)
+}
+
+// ensureDeployment serializes the first configuration read without holding the
+// node map lock across database access. All node workers copy this same snapshot.
+func (m *runtimeManager) ensureDeployment(parent context.Context) (bool, error) {
+	if m.loadDeployment == nil {
+		return true, nil
+	}
+	ctx, finish, err := m.enter(parent)
+	if err != nil {
+		return false, err
+	}
+	defer finish()
+	select {
+	case m.setupGate <- struct{}{}:
+	case <-ctx.Done():
+		return false, ctx.Err()
+	}
+	defer func() { <-m.setupGate }()
+	m.mu.Lock()
+	ready := m.config.Provider != nil
+	m.mu.Unlock()
+	if ready {
+		return true, nil
+	}
+	config, err := m.loadDeployment(ctx)
+	if err != nil || config == nil {
+		return false, err
+	}
+	if config.InstallationID != m.setupInstallationID || config.LocalNodeID != "" || config.loadDeployment != nil || (config.ProviderKind != "docker" && config.ProviderKind != "microsandbox") {
+		return false, sandbox.ErrInvalid
+	}
+	copied, err := validatedRuntimeProvider(config, m.registry)
+	if err != nil {
+		return false, err
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.closed || ctx.Err() != nil {
+		return false, ErrExecutionUnavailable
+	}
+	m.config = copied
+	return true, nil
+}
diff --git a/services/agents-api/internal/execution/sandbox_deployment_setup_test.go b/services/agents-api/internal/execution/sandbox_deployment_setup_test.go
new file mode 100644
index 000000000..ac16c7de2
--- /dev/null
+++ b/services/agents-api/internal/execution/sandbox_deployment_setup_test.go
@@ -0,0 +1,84 @@
+package execution
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	"github.com/MiniMax-AI-Dev/parsar/internal/agentdaemon/gateway"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox/node"
+	"github.com/google/uuid"
+)
+
+func TestDeferredSandboxDeploymentLoadsOnceBeforeNodeCreation(t *testing.T) {
+	hub := node.NewHub(node.HubOptions{})
+	defer hub.Close()
+	id := uuid.NewString()
+	var selected atomic.Bool
+	var loads atomic.Int32
+	configuration := &RuntimeProvider{InstallationID: id, ProviderKind: "docker", CoreURL: "https://core.example/api/v1", BackendFingerprint: strings.Repeat("a", 64), Provider: hub.Proxy(uuid.NewString(), "docker")}
+	m, err := newRuntimeManager(nil, gateway.NewRegistry(), NewDeferredRuntimeProvider(id, func(context.Context) (*RuntimeProvider, error) {
+		loads.Add(1)
+		if !selected.Load() {
+			return nil, nil
+		}
+		return configuration, nil
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { m.stop(); m.drain() })
+	if ready, err := m.ensureDeployment(t.Context()); err != nil || ready {
+		t.Fatal("empty setup became ready", ready, err)
+	}
+	if _, err := m.node("first"); !errors.Is(err, ErrExecutionUnavailable) {
+		t.Fatal("unconfigured node created", err)
+	}
+	selected.Store(true)
+	var wg sync.WaitGroup
+	for range 20 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if ready, err := m.ensureDeployment(t.Context()); err != nil || !ready {
+				t.Errorf("activation failed: %v %v", ready, err)
+			}
+		}()
+	}
+	wg.Wait()
+	if loads.Load() != 2 {
+		t.Fatal("configuration loaded again after selection", loads.Load())
+	}
+	configuration.CoreURL = "https://changed.example/api/v1"
+	a, err := m.node("first")
+	if err != nil || a.lifecycle.config.CoreURL != "https://core.example/api/v1" {
+		t.Fatal("mutable config reached worker", err)
+	}
+	m.stop()
+	if _, err := m.ensureDeployment(t.Context()); !errors.Is(err, ErrExecutionUnavailable) {
+		t.Fatal("stopped manager activated", err)
+	}
+}
+
+func TestDeferredSandboxDeploymentShutdownCancelsLoad(t *testing.T) {
+	entered := make(chan struct{})
+	m, err := newRuntimeManager(nil, gateway.NewRegistry(), NewDeferredRuntimeProvider(uuid.NewString(), func(ctx context.Context) (*RuntimeProvider, error) {
+		close(entered)
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	done := make(chan error, 1)
+	go func() { _, err := m.ensureDeployment(t.Context()); done <- err }()
+	<-entered
+	m.stop()
+	m.drain()
+	if err := <-done; !errors.Is(err, context.Canceled) {
+		t.Fatal("shutdown did not cancel setup load", err)
+	}
+}
diff --git a/services/agents-api/internal/execution/worker.go b/services/agents-api/internal/execution/worker.go
index fb6643471..b182417a2 100644
--- a/services/agents-api/internal/execution/worker.go
+++ b/services/agents-api/internal/execution/worker.go
@@ -39,12 +39,20 @@ func StartWorker(ctx context.Context, dispatcher *Dispatcher) (*Worker, error) {
 	}
 	var deployment *store.RuntimeDeployment
 	var verify store.RuntimeOwnershipVerifier
-	if worker.runtimes != nil {
+	if worker.runtimes != nil && worker.runtimes.loadDeployment == nil {
 		config := worker.runtimes.config
 		verify = config.VerifyLegacyOwnership
 		deployment = &store.RuntimeDeployment{ProviderKind: config.ProviderKind, LocalNodeID: config.LocalNodeID, LocalCredentialSHA256: config.LocalCredentialSHA256, LocalMaxActive: config.LocalMaxActive, LocalMaxRetained: config.LocalMaxRetained, InstallationID: config.InstallationID, BackendFingerprint: config.BackendFingerprint, Maintenance: config.Maintenance}
 	}
-	if err := owned.Store.ConfigureRuntimeDeployment(ctx, deployment, verify); err != nil {
+	if worker.runtimes != nil && worker.runtimes.loadDeployment != nil {
+		err = owned.Store.ClaimWebSandboxDeployment(ctx, worker.runtimes.setupInstallationID)
+		if err == nil {
+			_, err = worker.runtimes.ensureDeployment(ctx)
+		}
+	} else {
+		err = owned.Store.ConfigureRuntimeDeployment(ctx, deployment, verify)
+	}
+	if err != nil {
 		if worker.runtimes != nil {
 			worker.runtimes.stop()
 		}
diff --git a/services/agents-api/internal/store/runtime_deployment.go b/services/agents-api/internal/store/runtime_deployment.go
index 526ebb5be..6319181ab 100644
--- a/services/agents-api/internal/store/runtime_deployment.go
+++ b/services/agents-api/internal/store/runtime_deployment.go
@@ -58,6 +58,9 @@ func (s *Store) ConfigureRuntimeDeployment(ctx context.Context, selected *Runtim
 		if err != nil {
 			return err
 		}
+		if previous.WebManaged {
+			return ErrSandboxDeploymentConflict
+		}
 		if selected != nil && previous.InstallationID == update.InstallationID && previous.BackendFingerprint == update.BackendFingerprint && (previous.ProviderKind == "" || selected.ProviderKind == previous.ProviderKind) {
 			if err := q.SetRuntimeDeployment(ctx, update); err != nil {
 				return err
diff --git a/services/agents-api/internal/store/runtime_node_types.go b/services/agents-api/internal/store/runtime_node_types.go
index 3f86e33b8..3c4ab619e 100644
--- a/services/agents-api/internal/store/runtime_node_types.go
+++ b/services/agents-api/internal/store/runtime_node_types.go
@@ -67,6 +67,7 @@ type RuntimePlacement struct {
 	ComputePhase string `json:"compute_phase"`
 }
 type RuntimeDeploymentView struct {
+	CoreURL        string `json:"core_url"`
 	InstallationID string `json:"installation_id"`
 	Provider       string `json:"provider"`
 	Maintenance    bool   `json:"maintenance"`
diff --git a/services/agents-api/internal/store/runtime_nodes.go b/services/agents-api/internal/store/runtime_nodes.go
index 5b36fff4b..5bf1b22c5 100644
--- a/services/agents-api/internal/store/runtime_nodes.go
+++ b/services/agents-api/internal/store/runtime_nodes.go
@@ -48,7 +48,7 @@ func (s *Store) GetRuntimeDeployment(ctx context.Context) (RuntimeDeploymentView
 	if err != nil {
 		return RuntimeDeploymentView{}, err
 	}
-	return RuntimeDeploymentView{InstallationID: runtimeUUID(d.InstallationID), Provider: d.ProviderKind, Maintenance: d.Maintenance, OwnerEpoch: uint64(d.OwnerEpoch)}, nil
+	return runtimeDeploymentView(d), nil
 }
 func (s *Store) RuntimeOwnerEpoch(ctx context.Context) (uint64, error) {
 	d, err := s.queries.GetRuntimeDeployment(ctx)
diff --git a/services/agents-api/internal/store/runtime_placements.go b/services/agents-api/internal/store/runtime_placements.go
index ae9211154..d380701ac 100644
--- a/services/agents-api/internal/store/runtime_placements.go
+++ b/services/agents-api/internal/store/runtime_placements.go
@@ -17,7 +17,7 @@ func reserveRuntimePlacement(ctx context.Context, q *sqlc.Queries, session pgtyp
 		return err
 	}
 	if d.ProviderKind == "" {
-		if selected != "" {
+		if d.WebManaged || selected != "" {
 			return ErrRuntimeNodeUnavailable
 		}
 		return nil
diff --git a/services/agents-api/internal/store/sandbox_deployment_setup.go b/services/agents-api/internal/store/sandbox_deployment_setup.go
new file mode 100644
index 000000000..ee739ab91
--- /dev/null
+++ b/services/agents-api/internal/store/sandbox_deployment_setup.go
@@ -0,0 +1,163 @@
+package store
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"net"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/db/sqlc"
+	"github.com/jackc/pgx/v5"
+)
+
+var ErrSandboxDeploymentConflict = errors.New("sandbox deployment is already configured differently")
+
+type SandboxDeploymentSetupRequest struct {
+	Provider string `json:"provider"`
+	CoreURL  string `json:"core_url"`
+}
+
+// SandboxSetup is the immutable configuration selected by the deployment admin.
+// An empty Provider means that Web setup has not yet selected an adapter.
+type SandboxSetup struct {
+	InstallationID, Provider, CoreURL, BackendFingerprint string
+	IdleSeconds, RetentionSeconds                         int64
+}
+
+func (s *Store) GetSandboxSetup(ctx context.Context) (SandboxSetup, error) {
+	ctx, cancel := context.WithTimeout(ctx, executionTransactionTimeout)
+	defer cancel()
+	d, err := s.queries.GetRuntimeDeployment(ctx)
+	if err != nil {
+		return SandboxSetup{}, err
+	}
+	if !d.WebManaged {
+		return SandboxSetup{}, ErrSandboxDeploymentConflict
+	}
+	return SandboxSetup{InstallationID: runtimeUUID(d.InstallationID), Provider: d.ProviderKind, CoreURL: d.CoreUrl, BackendFingerprint: d.BackendFingerprint, IdleSeconds: d.IdleSeconds, RetentionSeconds: d.RetentionSeconds}, nil
+}
+
+// ClaimWebSandboxDeployment runs exactly once per execution-owner startup. It
+// reserves the installation before selection and fences previous node presence.
+func (s *Store) ClaimWebSandboxDeployment(ctx context.Context, installationID string) error {
+	id, err := parseConnectionGeneration(installationID)
+	if err != nil || s.executionLease == nil {
+		return ErrInvalidInput
+	}
+	ctx, cancel := context.WithTimeout(ctx, executionTransactionTimeout)
+	defer cancel()
+	return s.executionLease.transaction(ctx, func(tx pgx.Tx) error {
+		q := s.queries.WithTx(tx)
+		d, err := q.LockRuntimeDeployment(ctx)
+		if err != nil {
+			return err
+		}
+		if d.InstallationID.Valid {
+			if !d.WebManaged || d.InstallationID != id {
+				return ErrSandboxDeploymentConflict
+			}
+		} else {
+			resources, err := q.CountRuntimeDeploymentResources(ctx)
+			if err != nil {
+				return err
+			}
+			if resources.Allocations != 0 || resources.Pending != 0 {
+				return ErrSandboxDeploymentConflict
+			}
+		}
+		return q.ClaimWebSandboxDeployment(ctx, id)
+	})
+}
+
+// ValidateSandboxCoreURL accepts a canonical public origin, never a path or
+// credential. Plain HTTP is reserved for explicit loopback development hosts.
+func ValidateSandboxCoreURL(value string) error {
+	u, err := url.Parse(value)
+	if err != nil || u.Hostname() == "" || u.User != nil || u.Path != "" || u.RawPath != "" || u.RawQuery != "" || u.ForceQuery || u.Fragment != "" || u.RawFragment != "" || u.Opaque != "" || u.String() != value || u.Host != strings.ToLower(u.Host) {
+		return ErrInvalidInput
+	}
+	if strings.ContainsAny(u.Host, "\\% \t\r\n") || strings.HasSuffix(u.Host, ":") {
+		return ErrInvalidInput
+	}
+	if port := u.Port(); port != "" {
+		n, err := strconv.Atoi(port)
+		if err != nil || n < 1 || n > 65535 || strconv.Itoa(n) != port {
+			return ErrInvalidInput
+		}
+	}
+	loopback := u.Hostname() == "localhost"
+	if ip := net.ParseIP(u.Hostname()); ip != nil {
+		loopback = ip.IsLoopback()
+	} else {
+		if len(u.Hostname()) > 253 || strings.ContainsAny(u.Host, "[]") {
+			return ErrInvalidInput
+		}
+		for _, label := range strings.Split(u.Hostname(), ".") {
+			if len(label) == 0 || len(label) > 63 || label[0] == '-' || label[len(label)-1] == '-' {
+				return ErrInvalidInput
+			}
+			for _, char := range label {
+				if (char < 'a' || char > 'z') && (char < '0' || char > '9') && char != '-' {
+					return ErrInvalidInput
+				}
+			}
+		}
+	}
+	if u.Scheme != "https" && !(u.Scheme == "http" && loopback) {
+		return ErrInvalidInput
+	}
+	return nil
+}
+
+func (s *Store) InitializeSandboxDeployment(ctx context.Context, installationID string, input SandboxDeploymentSetupRequest) (RuntimeDeploymentView, error) {
+	if s.executionLease == nil || (input.Provider != "docker" && input.Provider != "microsandbox") || ValidateSandboxCoreURL(input.CoreURL) != nil {
+		return RuntimeDeploymentView{}, ErrInvalidInput
+	}
+	id, err := parseConnectionGeneration(installationID)
+	if err != nil {
+		return RuntimeDeploymentView{}, err
+	}
+	ctx, cancel := context.WithTimeout(ctx, executionTransactionTimeout)
+	defer cancel()
+	var result RuntimeDeploymentView
+	err = s.executionLease.transaction(ctx, func(tx pgx.Tx) error {
+		q := s.queries.WithTx(tx)
+		d, err := q.LockRuntimeDeployment(ctx)
+		if err != nil {
+			return err
+		}
+		if !d.WebManaged || d.InstallationID != id {
+			return ErrSandboxDeploymentConflict
+		}
+		if d.ProviderKind != "" {
+			if d.ProviderKind != input.Provider || d.CoreUrl != input.CoreURL {
+				return ErrSandboxDeploymentConflict
+			}
+			result = runtimeDeploymentView(d)
+			return nil
+		}
+		digest := sha256.Sum256([]byte(input.Provider + "\x00nodes:" + installationID))
+		params := sqlc.InitializeSandboxDeploymentParams{ProviderKind: input.Provider, CoreUrl: input.CoreURL, BackendFingerprint: hex.EncodeToString(digest[:])}
+		if input.Provider == "microsandbox" {
+			params.IdleSeconds, params.RetentionSeconds = 300, 86400
+		}
+		if err := q.InitializeSandboxDeployment(ctx, params); err != nil {
+			return err
+		}
+		d, err = q.GetRuntimeDeployment(ctx)
+		if err != nil {
+			return err
+		}
+		result = runtimeDeploymentView(d)
+		return nil
+	})
+	return result, err
+}
+
+func runtimeDeploymentView(d sqlc.RuntimeDeployment) RuntimeDeploymentView {
+	return RuntimeDeploymentView{InstallationID: runtimeUUID(d.InstallationID), Provider: d.ProviderKind, CoreURL: d.CoreUrl, Maintenance: d.Maintenance, OwnerEpoch: uint64(d.OwnerEpoch)}
+}
diff --git a/services/agents-api/internal/store/sandbox_deployment_setup_test.go b/services/agents-api/internal/store/sandbox_deployment_setup_test.go
new file mode 100644
index 000000000..8c60c8818
--- /dev/null
+++ b/services/agents-api/internal/store/sandbox_deployment_setup_test.go
@@ -0,0 +1,147 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestSandboxCoreURLValidation(t *testing.T) {
+	for _, value := range []string{"https://core.example", "https://core.example:8443", "http://localhost:8091", "http://127.0.0.2:8091", "http://[::1]:8091"} {
+		if err := ValidateSandboxCoreURL(value); err != nil {
+			t.Errorf("rejected %q: %v", value, err)
+		}
+	}
+	for _, value := range []string{"", "http://core.example", "http://core:8091", "http://host.localhost", "https://core.example/", "https://user:secret@core.example", "https://core.example/path", "https://core.example?", "https://core.example?q=x", "https://core.example#x", "https://core.example#", "https://CORE.example", "https://core.example:", "https://core.example:0", "https://core.example:65536", "https://core.example:0080", "https://core.example\\evil"} {
+		if err := ValidateSandboxCoreURL(value); !errors.Is(err, ErrInvalidInput) {
+			t.Errorf("accepted %q: %v", value, err)
+		}
+	}
+	for _, value := range []string{"https://[not-an-ip]", "https://-core.example", "https://core..example", "https://core_example"} {
+		if err := ValidateSandboxCoreURL(value); !errors.Is(err, ErrInvalidInput) {
+			t.Errorf("accepted invalid hostname %q: %v", value, err)
+		}
+	}
+}
+
+func TestSandboxDeploymentSetupPersistsWithoutExecution(t *testing.T) {
+	s, pool := newManagedTestStore(t)
+	lease := executionLease(t, s)
+	w := lease.Store()
+	id := uuid.NewString()
+	if err := w.ClaimWebSandboxDeployment(t.Context(), id); err != nil {
+		t.Fatal(err)
+	}
+	before, err := s.GetRuntimeDeployment(t.Context())
+	if err != nil || before.InstallationID != id || before.Provider != "" || before.CoreURL != "" {
+		t.Fatal(before, err)
+	}
+	if _, err := s.CreateSession(t.Context(), uuid.NewString(), managerSessionInput(uuid.NewString(), "")); !errors.Is(err, ErrRuntimeNodeUnavailable) {
+		t.Fatal("uninitialized hosted admission", err)
+	}
+	input := SandboxDeploymentSetupRequest{Provider: "microsandbox", CoreURL: "https://core.example"}
+	selected, err := w.InitializeSandboxDeployment(t.Context(), id, input)
+	if err != nil || selected.Provider != input.Provider || selected.CoreURL != input.CoreURL || selected.OwnerEpoch != before.OwnerEpoch {
+		t.Fatal(selected, err)
+	}
+	replay, err := w.InitializeSandboxDeployment(t.Context(), id, input)
+	if err != nil || replay != selected {
+		t.Fatal("identical retry changed selection", replay, err)
+	}
+	for _, changed := range []SandboxDeploymentSetupRequest{{Provider: "docker", CoreURL: input.CoreURL}, {Provider: input.Provider, CoreURL: "https://another.example"}} {
+		if _, err := w.InitializeSandboxDeployment(t.Context(), id, changed); !errors.Is(err, ErrSandboxDeploymentConflict) {
+			t.Fatal("changed selection accepted", err)
+		}
+	}
+	setup, err := s.GetSandboxSetup(t.Context())
+	if err != nil || setup.IdleSeconds != 300 || setup.RetentionSeconds != 86400 || !validRuntimeDigest(setup.BackendFingerprint) {
+		t.Fatal(setup, err)
+	}
+	var sideEffects int
+	if err := pool.QueryRow(t.Context(), "SELECT (SELECT count(*) FROM sessions)+(SELECT count(*) FROM runtime_nodes)+(SELECT count(*) FROM runtime_allocations)+(SELECT count(*) FROM runtime_placements)").Scan(&sideEffects); err != nil || sideEffects != 0 {
+		t.Fatal("setup or rejected admission created execution state", sideEffects, err)
+	}
+	if err := lease.Close(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	restarted := executionLease(t, s).Store()
+	if err := restarted.ClaimWebSandboxDeployment(t.Context(), id); err != nil {
+		t.Fatal(err)
+	}
+	after, err := s.GetSandboxSetup(t.Context())
+	if err != nil || after != setup {
+		t.Fatal("restart lost configuration", after, err)
+	}
+	epoch, err := s.RuntimeOwnerEpoch(t.Context())
+	if err != nil || epoch != before.OwnerEpoch+1 {
+		t.Fatal("restart did not fence node presence", epoch, err)
+	}
+	if err := restarted.ClaimWebSandboxDeployment(t.Context(), uuid.NewString()); !errors.Is(err, ErrSandboxDeploymentConflict) {
+		t.Fatal("installation replacement accepted", err)
+	}
+}
+
+func TestSandboxDeploymentSetupConcurrentSelection(t *testing.T) {
+	s, _ := newManagedTestStore(t)
+	w := executionLease(t, s).Store()
+	id := uuid.NewString()
+	if err := w.ClaimWebSandboxDeployment(t.Context(), id); err != nil {
+		t.Fatal(err)
+	}
+	var wg sync.WaitGroup
+	results := make(chan RuntimeDeploymentView, 20)
+	errorsFound := make(chan error, 20)
+	for i := range 20 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			provider := "docker"
+			if i%2 == 1 {
+				provider = "microsandbox"
+			}
+			value, err := w.InitializeSandboxDeployment(t.Context(), id, SandboxDeploymentSetupRequest{Provider: provider, CoreURL: "https://core.example"})
+			results <- value
+			errorsFound <- err
+		}()
+	}
+	wg.Wait()
+	close(results)
+	close(errorsFound)
+	conflicts := 0
+	for err := range errorsFound {
+		if errors.Is(err, ErrSandboxDeploymentConflict) {
+			conflicts++
+		} else if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if conflicts != 10 {
+		t.Fatal("both provider selections won", conflicts)
+	}
+	winner, err := s.GetSandboxSetup(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for result := range results {
+		if result.Provider != "" && result.Provider != winner.Provider {
+			t.Fatal("inconsistent selection", result)
+		}
+	}
+}
+
+func TestSandboxDeploymentSetupRejectsFileManagedAndUnleasedWrites(t *testing.T) {
+	s, w, selection := managerFixture(t, 4, 16)
+	input := SandboxDeploymentSetupRequest{Provider: "docker", CoreURL: "https://core.example"}
+	if _, err := s.InitializeSandboxDeployment(t.Context(), selection.InstallationID, input); !errors.Is(err, ErrInvalidInput) {
+		t.Fatal("unleased setup accepted", err)
+	}
+	if _, err := w.InitializeSandboxDeployment(t.Context(), selection.InstallationID, input); !errors.Is(err, ErrSandboxDeploymentConflict) {
+		t.Fatal("file-managed deployment changed", err)
+	}
+	if err := w.ClaimWebSandboxDeployment(t.Context(), selection.InstallationID); !errors.Is(err, ErrSandboxDeploymentConflict) {
+		t.Fatal("file-managed deployment adopted", err)
+	}
+}
diff --git a/services/agents-api/internal/store/sandbox_deployment_worker_test.go b/services/agents-api/internal/store/sandbox_deployment_worker_test.go
new file mode 100644
index 000000000..c4e30e034
--- /dev/null
+++ b/services/agents-api/internal/store/sandbox_deployment_worker_test.go
@@ -0,0 +1,88 @@
+package store_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/MiniMax-AI-Dev/parsar/internal/agentdaemon/gateway"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/execution"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+	"github.com/google/uuid"
+)
+
+func TestSandboxDeploymentWorkerActivatesWithoutRestart(t *testing.T) {
+	s, _ := store.NewManagedTestStore(t)
+	id := uuid.NewString()
+	p := &lifecycleProvider{resources: map[string]sandbox.Info{}}
+	configuration := execution.NewDeferredRuntimeProvider(id, func(ctx context.Context) (*execution.RuntimeProvider, error) {
+		setup, err := s.GetSandboxSetup(ctx)
+		if err != nil || setup.Provider == "" {
+			return nil, err
+		}
+		return &execution.RuntimeProvider{InstallationID: setup.InstallationID, ProviderKind: setup.Provider, BackendFingerprint: setup.BackendFingerprint, CoreURL: setup.CoreURL + "/api/v1", Provider: p}, nil
+	})
+	start := func() (*execution.Worker, func()) {
+		t.Helper()
+		w, err := execution.StartWorker(t.Context(), &execution.Dispatcher{Store: s, Registry: gateway.NewRegistry(), ManagedRuntimes: configuration})
+		if err != nil {
+			t.Fatal(err)
+		}
+		var once sync.Once
+		stop := func() {
+			once.Do(func() { ctx, cancel := context.WithCancel(context.Background()); cancel(); _ = w.Run(ctx) })
+		}
+		t.Cleanup(stop)
+		return w, stop
+	}
+	w, stop := start()
+	input := store.CreateSessionInput{Creator: store.FixtureCreator(), Engine: "codex", IdempotencyKey: uuid.NewString(), Configuration: json.RawMessage(`{"agent":{"model":"test"},"environment":{"type":"openai_hosted","network":{"access":"disabled"}}}`)}
+	if _, err := w.CreateSession(t.Context(), uuid.NewString(), input); !errors.Is(err, execution.ErrExecutionUnavailable) {
+		t.Fatal("uninitialized worker admitted hosted Session", err)
+	}
+	if _, err := w.InitializeSandboxDeployment(t.Context(), store.SandboxDeploymentSetupRequest{Provider: "docker", CoreURL: "https://core.example"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.CreateSession(t.Context(), uuid.NewString(), input); !errors.Is(err, store.ErrRuntimeNodeUnavailable) {
+		t.Fatal("zero-node deployment admitted Session", err)
+	}
+	token, _, err := s.CreateRuntimeEnrollment(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	nodeID := uuid.NewString()
+	if _, err := s.EnrollRuntimeNode(t.Context(), token, store.RuntimeNodeEnrollment{NodeID: nodeID, Name: "Remote", Provider: "docker", Credential: strings.Repeat("x", 64), BackendFingerprint: strings.Repeat("b", 64), MaxActive: 4, MaxRetained: 16}); err != nil {
+		t.Fatal(err)
+	}
+	connect := func() {
+		t.Helper()
+		epoch, err := s.RuntimeOwnerEpoch(t.Context())
+		if err != nil {
+			t.Fatal(err)
+		}
+		connection := uuid.NewString()
+		if err := s.ConnectRuntimeNode(t.Context(), nodeID, connection, epoch); err != nil {
+			t.Fatal(err)
+		}
+		if err := s.HeartbeatRuntimeNode(t.Context(), nodeID, connection, epoch, store.RuntimeNodeHealth{ProviderReady: true}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	connect()
+	tenant, _, environment := managedSession(t, s)
+	allocation, err := w.ProvisionEnvironment(t.Context(), tenant, environment.ID, id)
+	if err != nil || allocation.NodeID != nodeID || p.creates != 1 {
+		t.Fatal("activation failed", allocation, err)
+	}
+	stop()
+	w, _ = start()
+	connect()
+	replayed, err := w.ProvisionEnvironment(t.Context(), tenant, environment.ID, id)
+	if err != nil || replayed.ID != allocation.ID || !replayed.Replayed || p.creates != 1 {
+		t.Fatal("restart changed allocation ownership", replayed, err)
+	}
+}
diff --git a/services/agents-api/migrations/000058_sandbox_deployment_setup.sql b/services/agents-api/migrations/000058_sandbox_deployment_setup.sql
new file mode 100644
index 000000000..80aa81826
--- /dev/null
+++ b/services/agents-api/migrations/000058_sandbox_deployment_setup.sql
@@ -0,0 +1,38 @@
+-- +goose Up
+ALTER TABLE runtime_deployment ADD COLUMN web_managed boolean NOT NULL DEFAULT false;
+ALTER TABLE runtime_deployment ADD COLUMN core_url text NOT NULL DEFAULT '';
+ALTER TABLE runtime_deployment ADD COLUMN idle_seconds bigint NOT NULL DEFAULT 0 CHECK (idle_seconds >= 0);
+ALTER TABLE runtime_deployment ADD COLUMN retention_seconds bigint NOT NULL DEFAULT 0 CHECK (retention_seconds >= 0);
+ALTER TABLE runtime_deployment DROP CONSTRAINT runtime_deployment_check;
+ALTER TABLE runtime_deployment ADD CONSTRAINT runtime_deployment_identity_check CHECK (
+    (installation_id IS NULL AND backend_fingerprint = '') OR
+    (installation_id IS NOT NULL AND backend_fingerprint ~ '^[0-9a-f]{64}$') OR
+    (web_managed AND installation_id IS NOT NULL AND provider_kind = '' AND backend_fingerprint = '')
+);
+ALTER TABLE runtime_deployment ADD CONSTRAINT runtime_deployment_setup_check CHECK (
+    NOT web_managed OR (local_node_id IS NULL AND (
+        (provider_kind = '' AND core_url = '' AND idle_seconds = 0 AND retention_seconds = 0) OR
+        (provider_kind = 'docker' AND core_url <> '' AND idle_seconds = 0 AND retention_seconds = 0) OR
+        (provider_kind = 'microsandbox' AND core_url <> '' AND idle_seconds > 0 AND retention_seconds > 0)
+    ))
+);
+
+-- +goose Down
+-- +goose StatementBegin
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM runtime_deployment WHERE web_managed) THEN
+        RAISE EXCEPTION 'Cannot discard Web-managed sandbox deployment setup';
+    END IF;
+END $$;
+-- +goose StatementEnd
+ALTER TABLE runtime_deployment DROP CONSTRAINT runtime_deployment_setup_check;
+ALTER TABLE runtime_deployment DROP CONSTRAINT runtime_deployment_identity_check;
+ALTER TABLE runtime_deployment DROP COLUMN retention_seconds;
+ALTER TABLE runtime_deployment DROP COLUMN idle_seconds;
+ALTER TABLE runtime_deployment DROP COLUMN core_url;
+ALTER TABLE runtime_deployment DROP COLUMN web_managed;
+ALTER TABLE runtime_deployment ADD CONSTRAINT runtime_deployment_check CHECK (
+    (installation_id IS NULL AND backend_fingerprint = '') OR
+    (installation_id IS NOT NULL AND backend_fingerprint ~ '^[0-9a-f]{64}$')
+);

From eb1417c61a5acf99756ce2417d91c07e783c6037 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:46:01 +0800
Subject: [PATCH 3/9] feat(node): install and enroll matched runtime from
 bundled console

---
 deploy/install/node_install.py      | 301 ++++++++++++++++++++++++++++
 deploy/install/test_node_install.py | 197 ++++++++++++++++++
 2 files changed, 498 insertions(+)
 create mode 100644 deploy/install/node_install.py
 create mode 100644 deploy/install/test_node_install.py

diff --git a/deploy/install/node_install.py b/deploy/install/node_install.py
new file mode 100644
index 000000000..4870ca568
--- /dev/null
+++ b/deploy/install/node_install.py
@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""Install and enroll one node from its Core console's matched distribution."""
+import argparse
+import fcntl
+import hashlib
+import ipaddress
+import json
+import os
+from pathlib import Path
+import platform
+import re
+import socket
+import stat
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from urllib.parse import urlsplit
+import uuid
+
+
+class InstallError(Exception):
+    pass
+
+
+COMMON = ("native/bin/parsar-sandbox-node", "images/runtime.tar", "runtime/seccomp.json")
+MICRO = ("native/bin/agents-api-microsandbox-provider", "native/microsandbox/msb",
+         "native/microsandbox/libkrunfw.so.5.6.1")
+
+
+def origin(value):
+    try:
+        parsed = urlsplit(value)
+        parsed.port
+    except ValueError:
+        raise argparse.ArgumentTypeError("Invalid Core origin") from None
+    try:
+        local = parsed.hostname == "localhost" or ipaddress.ip_address(parsed.hostname).is_loopback
+    except (ValueError, TypeError):
+        local = parsed.hostname == "localhost"
+    if (parsed.scheme not in ("http", "https") or not parsed.hostname or parsed.username is not None
+            or parsed.password is not None or parsed.path not in ("", "/")
+            or any(c.isspace() for c in value) or any(c in value for c in "?#\\")
+            or (parsed.scheme == "http" and not local)):
+        raise argparse.ArgumentTypeError("Use an HTTPS origin, or loopback HTTP for a local node")
+    return value.rstrip("/")
+
+
+def checked(arguments, failure, **kwargs):
+    try:
+        result = subprocess.run(arguments, check=False, stdin=subprocess.DEVNULL,
+                                stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=kwargs.pop("timeout", 30), **kwargs)
+        if result.returncode:
+            raise InstallError(failure)
+        return result.stdout.decode().strip()
+    except (OSError, subprocess.SubprocessError):
+        raise InstallError(failure) from None
+
+
+def preflight(provider):
+    if sys.version_info < (3, 9) or platform.system() != "Linux" or platform.machine() not in ("x86_64", "amd64") or os.getuid() == 0:
+        raise InstallError("Run with Python 3.9+ as a non-root user on Linux amd64")
+    checked(["systemctl", "--user", "show", "--property=Version", "--value"], "A systemd user session is required")
+    if checked(["loginctl", "show-user", str(os.getuid()), "--property=Linger", "--value"], "Cannot check user lingering") != "yes":
+        raise InstallError("Ask the host administrator to enable user lingering before installing a node")
+    if provider == "docker":
+        checked(["docker", "--host", "unix:///var/run/docker.sock", "info", "--format", "{{.ServerVersion}}"], "Docker access through /var/run/docker.sock is required")
+    elif not os.access("/dev/kvm", os.R_OK | os.W_OK):
+        raise InstallError("microsandbox requires read/write access to /dev/kvm")
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, request, fp, code, message, headers, url):
+        raise InstallError("Node payload redirects are not supported")
+
+
+def fetch(source, name):
+    return urllib.request.build_opener(NoRedirect()).open(source + "/node-install/" + name, timeout=30)
+
+
+def metadata(source):
+    with fetch(source, "SHA256SUMS") as response:
+        raw = response.read(1024 * 1024 + 1)
+    if len(raw) > 1024 * 1024:
+        raise InstallError("Invalid distribution checksum list")
+    sums = {}
+    for line in raw.decode().splitlines():
+        checksum, name = line.split("  ", 1)
+        if name in sums or not re.fullmatch(r"[0-9a-f]{64}", checksum):
+            raise InstallError("Invalid distribution checksum entry")
+        sums[name] = checksum
+    with fetch(source, "manifest.json") as response:
+        raw = response.read(1024 * 1024 + 1)
+    if len(raw) > 1024 * 1024 or hashlib.sha256(raw).hexdigest() != sums.get("manifest.json"):
+        raise InstallError("Distribution manifest checksum mismatch")
+    manifest = json.loads(raw)
+    if (manifest.get("platform") != "linux/amd64" or not re.fullmatch(r"[0-9a-f]{40}", manifest.get("source_commit", ""))
+            or not re.fullmatch(r"sha256:[0-9a-f]{64}", manifest.get("images", {}).get("runtime", ""))):
+        raise InstallError("Unsupported node distribution")
+    return manifest, sums
+
+
+def safe_directory(path):
+    if not path.is_absolute() or path.resolve() != path or any(ord(c) < 32 or c in "\\*?[]" for c in str(path)):
+        raise InstallError("Node installation path must be canonical without symlinks or control characters")
+    path.mkdir(parents=True, mode=0o700, exist_ok=True)
+    if not path.is_dir() or path.stat().st_uid != os.getuid():
+        raise InstallError("Node installation directory must be owned by this user")
+    os.chmod(path, 0o700)
+
+
+def existing_file(path):
+    if path.is_symlink() or (path.exists() and not path.is_file()):
+        raise InstallError("Node installation files must be regular files, never symlinks")
+    if path.exists() and (path.stat().st_uid != os.getuid() or stat.S_IMODE(path.stat().st_mode) & 0o077):
+        raise InstallError("Node installation files must be private and owned by this user")
+    return path.exists()
+
+
+def write_once(path, value):
+    if existing_file(path):
+        if path.read_text() != value:
+            raise InstallError("Existing node configuration differs; preserve its state and use the upgrade guide")
+        return
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(descriptor, "w") as stream:
+        stream.write(value)
+
+
+def json_text(value):
+    return json.dumps(value, indent=2, sort_keys=True) + "\n"
+
+
+def file_digest(path):
+    result = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            result.update(block)
+    return result.hexdigest()
+
+
+def download(source, name, root, expected):
+    target = root / name
+    safe_directory(target.parent)
+    if existing_file(target):
+        if file_digest(target) != expected:
+            raise InstallError("Installed node payload differs; refusing to overwrite it")
+        return
+    descriptor, temporary = tempfile.mkstemp(prefix=".download-", dir=target.parent)
+    try:
+        with os.fdopen(descriptor, "wb") as output, fetch(source, name) as response:
+            for block in iter(lambda: response.read(1024 * 1024), b""):
+                output.write(block)
+        if file_digest(Path(temporary)) != expected:
+            raise InstallError("Node payload checksum mismatch: " + name)
+        os.replace(temporary, target)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+    if name.startswith("native/"):
+        os.chmod(target, 0o700)
+
+
+def micro_home(installation_id):
+    directory = Path.home() / ".parsar/m" / hashlib.sha256(installation_id.encode()).hexdigest()[:12]
+    if len(os.fsencode(directory)) > 48:
+        raise InstallError("HOME is too long for microsandbox Unix socket paths; use a user with a shorter persistent home directory")
+    return directory
+
+
+def provider_config(root, args, manifest):
+    result = {"installation_id": args.installation_id, "provider": args.provider, "core_url": args.core_url + "/api/v1"}
+    if args.provider == "docker":
+        result["docker"] = {"host": "unix:///var/run/docker.sock", "image": manifest["images"]["runtime"],
+                            "network": "parsar-node-" + args.installation_id,
+                            "seccomp_file": str(root / "runtime/seccomp.json"), "nested_sandbox": True}
+    else:
+        endpoint = urlsplit(args.core_url)
+        port = endpoint.port or (443 if endpoint.scheme == "https" else 80)
+        addresses = sorted({entry[4][0] for entry in socket.getaddrinfo(endpoint.hostname, port, type=socket.SOCK_STREAM)})
+        core_rules = [{"action": "allow", "direction": "egress", "destination": address, "protocol": "tcp", "port": str(port)} for address in addresses]
+        result["microsandbox"] = {
+            "helper_path": str(root / MICRO[0]), "runtime_path": str(root / MICRO[1]), "firmware_path": str(root / MICRO[2]),
+            "runtime_sha256": manifest["microsandbox"]["runtime_sha256"], "firmware_sha256": manifest["microsandbox"]["firmware_sha256"],
+            "runtime_home": str(micro_home(args.installation_id)), "image": manifest["runtime_ref"], "memory_mib": 4096, "cpus": 2,
+            "root_disk_mib": 8192, "environment_disk_mib": 8192, "idle_seconds": 300, "retention_seconds": 86400,
+            "max_active": 4, "max_retained": 16,
+            "network": {"default_egress": "deny", "default_ingress": "deny", "rules": core_rules + [
+                {"action": "allow", "direction": "egress", "destination": "public"},
+                {"action": "allow", "direction": "egress", "destination": "host", "protocol": "udp", "port": "53"},
+                {"action": "allow", "direction": "egress", "destination": "host", "protocol": "tcp", "port": "53"},
+            ]},
+        }
+    return result
+
+
+def prepare_runtime(root, args, manifest):
+    if args.provider == "docker":
+        docker = ["docker", "--host", "unix:///var/run/docker.sock"]
+        checked(docker + ["load", "--input", str(root / "images/runtime.tar")], "Cannot import the Docker runtime image", timeout=1800)
+        image = checked(docker + ["image", "inspect", "--format", "{{.Id}}", manifest["images"]["runtime"]], "Cannot verify the runtime image")
+        if image != manifest["images"]["runtime"]:
+            raise InstallError("Imported runtime image identity differs")
+        network = "parsar-node-" + args.installation_id
+        networks = checked(docker + ["network", "ls", "--format", "{{.Name}}"], "Cannot inspect Docker networks").splitlines()
+        if network not in networks:
+            checked(docker + ["network", "create", network], "Cannot create node Docker network")
+    else:
+        for name in MICRO:
+            result = subprocess.run(["ldd", str(root / name)], stdout=subprocess.PIPE, stderr=subprocess.STDOUT, timeout=30)
+            output = result.stdout.decode()
+            if "not found" in output or (result.returncode and "statically linked" not in output and "not a dynamic executable" not in output):
+                raise InstallError("Install the microsandbox host shared-library prerequisites")
+        checked([str(root / MICRO[1]), "image", "load", "--input", str(root / "images/runtime.tar"), "--tag", manifest["runtime_ref"], "--quiet"],
+                "Cannot import the microsandbox runtime image", timeout=1800,
+                env=dict(os.environ, MSB_BACKEND="local", MSB_HOME=str(micro_home(args.installation_id)), MSB_PATH=str(root / MICRO[1]), MSB_LIBKRUNFW_PATH=str(root / MICRO[2])))
+
+
+def service_unit(root):
+    def quote(value):
+        return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"').replace("%", "%%") + '"'
+    return ("[Unit]\nDescription=Parsar sandbox node\n\n[Service]\nType=exec\nExecStart=:"
+            + quote(root / COMMON[0]) + " run --config " + quote(root / "provider.json") + " --state-dir " + quote(root / "state/node")
+            + "\nWorkingDirectory=" + str(root).replace("%", "%%")
+            + "\nRestart=on-failure\nKillMode=process\nUMask=0077\n\n[Install]\nWantedBy=default.target\n")
+
+
+def install(args, token):
+    preflight(args.provider)
+    if args.provider == "microsandbox":
+        runtime_home = micro_home(args.installation_id)
+        safe_directory(runtime_home)
+        owner = runtime_home / "parsar-installation.json"
+        if not owner.exists() and any(runtime_home.iterdir()):
+            raise InstallError("Microsandbox home contains unowned state; refusing to adopt it")
+        write_once(owner, json_text({"installation_id": args.installation_id}))
+    root = Path.home() / ".parsar/nodes" / args.installation_id
+    safe_directory(root)
+    descriptor = os.open(root / "install.lock", os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    with os.fdopen(descriptor, "w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise InstallError("Another node installation is running") from None
+        manifest, sums = metadata(args.source_url)
+        names = COMMON + (MICRO if args.provider == "microsandbox" else ())
+        if any(name not in sums for name in names):
+            raise InstallError("The distribution is missing required node checksums")
+        state = {"installation_id": args.installation_id, "provider": args.provider, "core_url": args.core_url,
+                 "source_commit": manifest["source_commit"]}
+        write_once(root / "installation.json", json_text(state))
+        for name in names:
+            download(args.source_url, name, root, sums[name])
+        safe_directory(root / "state/node")
+        write_once(root / "provider.json", json_text(provider_config(root, args, manifest)))
+        unit = root / ("parsar-node-" + args.installation_id + ".service")
+        write_once(unit, service_unit(root))
+        marker = root / "registered.json"
+        if not existing_file(marker):
+            prepare_runtime(root, args, manifest)
+            # The one-time credential is never passed through process arguments or service environments.
+            descriptor, secret_path = tempfile.mkstemp(prefix=".enrollment-", dir=root)
+            try:
+                with os.fdopen(descriptor, "w") as secret:
+                    secret.write(token)
+                checked([str(root / COMMON[0]), "register", "--config", str(root / "provider.json"), "--state-dir", str(root / "state/node"),
+                         "--core-url", args.core_url, "--name", socket.gethostname(), "--max-active", "4", "--max-retained", "16",
+                         "--enrollment-token-file", secret_path], "Node enrollment was not confirmed. Keep its state and rerun the command to recover.")
+                write_once(marker, json_text(state))
+            finally:
+                if os.path.exists(secret_path):
+                    os.unlink(secret_path)
+        elif marker.read_text() != json_text(state):
+            raise InstallError("Registered node identity differs; refusing to replace it")
+        checked(["systemctl", "--user", "daemon-reload"], "Cannot reload the systemd user manager")
+        checked(["systemctl", "--user", "enable", "--now", str(unit)], "Cannot start the node service; retained identity is unchanged")
+        checked(["systemctl", "--user", "is-active", "--quiet", unit.name], "Node service is unavailable; inspect its systemd user journal")
+    print("Node service started. The Web console will show connection and provider readiness. State: " + str(root))
+
+
+def main(argv=None):
+    token = os.environ.pop("PARSAR_NODE_ENROLLMENT_TOKEN", "")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source-url", type=origin, required=True)
+    parser.add_argument("--core-url", type=origin, required=True)
+    parser.add_argument("--provider", choices=("docker", "microsandbox"), required=True)
+    parser.add_argument("--installation-id", required=True)
+    args = parser.parse_args(argv)
+    if str(uuid.UUID(args.installation_id)) != args.installation_id:
+        raise InstallError("Installation ID must be a canonical UUID")
+    if not token or len(token) > 4096 or any(c.isspace() for c in token):
+        raise InstallError("A valid one-time enrollment credential is required")
+    install(args, token)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (InstallError, OSError, ValueError, KeyError, subprocess.SubprocessError) as error:
+        print(str(error) if isinstance(error, InstallError) else "Node installation failed; check host prerequisites and retained private files", file=sys.stderr)
+        sys.exit(1)
diff --git a/deploy/install/test_node_install.py b/deploy/install/test_node_install.py
new file mode 100644
index 000000000..15aee3175
--- /dev/null
+++ b/deploy/install/test_node_install.py
@@ -0,0 +1,197 @@
+"""Exercise node installation without running providers or changing user services."""
+import argparse
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import stat
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+
+import node_install as installer
+
+
+class NodeInstallTests(unittest.TestCase):
+    def setUp(self):
+        base = Path.home() / ".parsar/tests/node-install"
+        base.mkdir(parents=True, exist_ok=True)
+        temporary = tempfile.TemporaryDirectory(dir=base)
+        self.addCleanup(temporary.cleanup)
+        self.home = Path(temporary.name).resolve()
+        self.args = argparse.Namespace(source_url="https://console.example", core_url="https://172.29.144.1:24443",
+                                       provider="docker", installation_id="94be54a1-138c-4f30-bc87-b13686272dbe")
+        self.root = self.home / ".parsar/nodes" / self.args.installation_id
+        self.manifest = {"platform": "linux/amd64", "source_commit": "a" * 40, "images": {"runtime": "sha256:" + "b" * 64},
+                         "runtime_ref": "parsar-core-runtime@sha256:" + "c" * 64,
+                         "microsandbox": {"runtime_sha256": "d" * 64, "firmware_sha256": "e" * 64}}
+        self.payloads = {name: b"fixture-payload-" + name.encode() for name in installer.COMMON + installer.MICRO}
+        self.refresh_manifest()
+        self.calls = []
+        self.fail_service = False
+        self.fail_registration = False
+        for patch in (mock.patch.object(installer.Path, "home", return_value=self.home),
+                      mock.patch.object(installer, "preflight"),
+                      mock.patch.object(installer, "micro_home", return_value=self.home / "m"),
+                      mock.patch.object(installer, "fetch", side_effect=lambda source, name: io.BytesIO(self.payloads[name])),
+                      mock.patch.object(installer, "checked", side_effect=self.checked),
+                      mock.patch.object(installer.subprocess, "run", return_value=subprocess.CompletedProcess([], 0, b"statically linked", b""))):
+            patch.start()
+            self.addCleanup(patch.stop)
+
+    def refresh_manifest(self):
+        self.payloads["manifest.json"] = json.dumps(self.manifest).encode()
+        self.payloads["SHA256SUMS"] = "".join(hashlib.sha256(raw).hexdigest() + "  " + name + "\n"
+                                               for name, raw in self.payloads.items() if name != "SHA256SUMS").encode()
+
+    def checked(self, arguments, failure, **kwargs):
+        self.calls.append((arguments, kwargs))
+        self.assertNotIn("synthetic-once-token", str(arguments))
+        self.assertNotIn("PARSAR_NODE_ENROLLMENT_TOKEN", os.environ)
+        if "register" in arguments:
+            secret = Path(arguments[arguments.index("--enrollment-token-file") + 1])
+            self.assertEqual(secret.read_text(), "synthetic-once-token")
+            self.assertEqual(stat.S_IMODE(secret.stat().st_mode), 0o600)
+            if self.fail_registration:
+                raise installer.InstallError(failure)
+        if "enable" in arguments and self.fail_service:
+            raise installer.InstallError(failure)
+        return self.manifest["images"]["runtime"] if "inspect" in arguments else ""
+
+    def install(self):
+        installer.install(self.args, "synthetic-once-token")
+
+    def test_docker_installs_matched_payload_registers_and_starts_persistent_service(self):
+        self.install()
+        config = json.loads((self.root / "provider.json").read_text())
+        self.assertEqual(config["docker"]["image"], self.manifest["images"]["runtime"])
+        self.assertEqual(config["core_url"], self.args.core_url + "/api/v1")
+        self.assertEqual(config["installation_id"], self.args.installation_id)
+        self.assertFalse((self.root / installer.MICRO[0]).exists())
+        unit = (self.root / ("parsar-node-" + self.args.installation_id + ".service")).read_text()
+        self.assertIn(" run --config ", unit)
+        self.assertIn("KillMode=process", unit)
+        self.assertNotIn("synthetic-once-token", unit)
+        self.assertEqual(list(self.root.glob(".enrollment-*")), [])
+        self.assertTrue(any("register" in call for call, _ in self.calls))
+        self.assertTrue(any("is-active" in call for call, _ in self.calls))
+
+    def test_microsandbox_imports_image_and_allows_only_explicit_private_core_endpoint(self):
+        self.args.provider = "microsandbox"
+        self.install()
+        config = json.loads((self.root / "provider.json").read_text())["microsandbox"]
+        self.assertEqual(config["runtime_sha256"], self.manifest["microsandbox"]["runtime_sha256"])
+        self.assertEqual(config["idle_seconds"], 300)
+        self.assertEqual(config["retention_seconds"], 86400)
+        rules = config["network"]["rules"]
+        self.assertIn({"action": "allow", "direction": "egress", "destination": "172.29.144.1", "protocol": "tcp", "port": "24443"}, rules)
+        self.assertNotIn("private", [rule["destination"] for rule in rules])
+        self.assertTrue(any("--tag" in call and self.manifest["runtime_ref"] in call for call, _ in self.calls))
+
+    def test_repeat_preserves_registration_and_recovers_service_start_failure(self):
+        self.fail_service = True
+        with self.assertRaisesRegex(installer.InstallError, "Cannot start"):
+            self.install()
+        saved = (self.root / "registered.json").read_bytes()
+        self.calls.clear()
+        self.fail_service = False
+        self.install()
+        self.assertEqual((self.root / "registered.json").read_bytes(), saved)
+        self.assertFalse(any("register" in call for call, _ in self.calls))
+        self.assertFalse(any("load" in call for call, _ in self.calls))
+
+    def test_unconfirmed_registration_retains_state_removes_token_and_does_not_start(self):
+        self.fail_registration = True
+        with self.assertRaisesRegex(installer.InstallError, "not confirmed"):
+            self.install()
+        self.assertTrue((self.root / "provider.json").is_file())
+        self.assertFalse((self.root / "registered.json").exists())
+        self.assertEqual(list(self.root.glob(".enrollment-*")), [])
+        self.assertFalse(any("enable" in call for call, _ in self.calls))
+
+    def test_different_commit_provider_or_core_cannot_overwrite_retained_installation(self):
+        self.install()
+        original = (self.root / "provider.json").read_bytes()
+        for field, value in (("provider", "microsandbox"), ("core_url", "https://other.example")):
+            before = getattr(self.args, field)
+            setattr(self.args, field, value)
+            with self.assertRaisesRegex(installer.InstallError, "configuration differs"):
+                self.install()
+            setattr(self.args, field, before)
+        self.manifest["source_commit"] = "f" * 40
+        self.refresh_manifest()
+        with self.assertRaisesRegex(installer.InstallError, "configuration differs"):
+            self.install()
+        self.assertEqual((self.root / "provider.json").read_bytes(), original)
+
+    def test_corrupt_manifest_and_payload_fail_before_provider_use(self):
+        self.payloads["manifest.json"] += b" "
+        with self.assertRaisesRegex(installer.InstallError, "manifest checksum"):
+            self.install()
+        self.refresh_manifest()
+        self.payloads[installer.COMMON[0]] += b"corrupt"
+        with self.assertRaisesRegex(installer.InstallError, "payload checksum"):
+            self.install()
+        self.assertFalse(self.calls)
+        self.assertFalse((self.root / installer.COMMON[0]).exists())
+
+    def test_installed_payload_and_config_are_not_overwritten(self):
+        self.install()
+        target = self.root / installer.COMMON[0]
+        target.write_bytes(b"existing-different-payload")
+        with self.assertRaisesRegex(installer.InstallError, "refusing to overwrite"):
+            self.install()
+        self.assertEqual(target.read_bytes(), b"existing-different-payload")
+
+    def test_symlink_installation_is_rejected(self):
+        self.root.parent.mkdir(parents=True)
+        elsewhere = self.home / "elsewhere"
+        elsewhere.mkdir()
+        self.root.symlink_to(elsewhere, target_is_directory=True)
+        with self.assertRaisesRegex(installer.InstallError, "symlinks"):
+            self.install()
+        self.assertEqual(list(elsewhere.iterdir()), [])
+
+    def test_main_removes_token_environment_before_any_subprocess(self):
+        with mock.patch.dict(os.environ, {"PARSAR_NODE_ENROLLMENT_TOKEN": "synthetic-once-token"}):
+            installer.main(["--source-url", self.args.source_url, "--core-url", self.args.core_url,
+                            "--provider", "docker", "--installation-id", self.args.installation_id])
+            self.assertNotIn("PARSAR_NODE_ENROLLMENT_TOKEN", os.environ)
+
+    def test_origin_rejects_remote_http_credentials_paths_and_redirects(self):
+        for value in ("http://private.example", "https://user@core.example", "https://@core.example", "https://core.example/v1", "https://core.example?", "https://core.example#", "https://core.example\\path", "https://core.example:bad", ""):
+            with self.subTest(value=value), self.assertRaises(argparse.ArgumentTypeError):
+                installer.origin(value)
+        self.assertEqual(installer.origin("http://[::1]:8091/"), "http://[::1]:8091")
+        with self.assertRaisesRegex(installer.InstallError, "redirects"):
+            installer.NoRedirect().redirect_request(None, None, 302, "", {}, "https://other.example")
+
+
+class NodePrerequisiteTests(unittest.TestCase):
+    def test_preflight_rejects_missing_linger_or_kvm_before_downloads(self):
+        with mock.patch.object(installer.platform, "system", return_value="Linux"), \
+             mock.patch.object(installer.platform, "machine", return_value="x86_64"), \
+             mock.patch.object(installer.os, "getuid", return_value=1000), \
+             mock.patch.object(installer, "checked", return_value="no"), \
+             mock.patch.object(installer, "fetch") as fetch:
+            with self.assertRaisesRegex(installer.InstallError, "lingering"):
+                installer.preflight("docker")
+            fetch.assert_not_called()
+            with mock.patch.object(installer, "checked", return_value="yes"), mock.patch.object(installer.os, "access", return_value=False):
+                with self.assertRaisesRegex(installer.InstallError, "KVM"):
+                    installer.preflight("microsandbox")
+
+    def test_microsandbox_short_home_is_stable_and_rejects_long_user_home(self):
+        with mock.patch.object(installer.Path, "home", return_value=Path("/home/node")):
+            first = installer.micro_home("94be54a1-138c-4f30-bc87-b13686272dbe")
+            self.assertEqual(first, installer.micro_home("94be54a1-138c-4f30-bc87-b13686272dbe"))
+            self.assertLessEqual(len(os.fsencode(first)), 48)
+        with mock.patch.object(installer.Path, "home", return_value=Path("/home/" + "long" * 20)):
+            with self.assertRaisesRegex(installer.InstallError, "HOME is too long"):
+                installer.micro_home("94be54a1-138c-4f30-bc87-b13686272dbe")
+
+
+if __name__ == "__main__":
+    unittest.main()

From e039ef93abe48b7493501f9a23adcdcb229e8be8 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:46:10 +0800
Subject: [PATCH 4/9] test(node): match KVM prerequisite diagnostic

---
 deploy/install/test_node_install.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/deploy/install/test_node_install.py b/deploy/install/test_node_install.py
index 15aee3175..de656b7f6 100644
--- a/deploy/install/test_node_install.py
+++ b/deploy/install/test_node_install.py
@@ -180,7 +180,7 @@ def test_preflight_rejects_missing_linger_or_kvm_before_downloads(self):
                 installer.preflight("docker")
             fetch.assert_not_called()
             with mock.patch.object(installer, "checked", return_value="yes"), mock.patch.object(installer.os, "access", return_value=False):
-                with self.assertRaisesRegex(installer.InstallError, "KVM"):
+                with self.assertRaisesRegex(installer.InstallError, "/dev/kvm"):
                     installer.preflight("microsandbox")
 
     def test_microsandbox_short_home_is_stable_and_rejects_long_user_home(self):

From 557d0d0293dac9ac6f472efd734dfc6015133896 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:49:01 +0800
Subject: [PATCH 5/9] feat(web): enroll nodes with paired console login and one
 install command

---
 apps/web/e2e/sandbox-setup.spec.ts            | 29 ++++++++++++++++
 .../src/features/sandbox/NodeEnrollment.tsx   | 33 +++++++++++++++----
 .../features/sandbox/SandboxManagerView.tsx   | 31 +++++++++++++----
 .../web/src/features/sandbox/SandboxSetup.tsx |  5 +--
 .../features/sandbox/console-config.test.ts   | 21 ++++++++++++
 .../src/features/sandbox/console-config.ts    | 18 ++++++++++
 .../sandbox/enrollment-command.test.ts        | 12 ++++++-
 .../features/sandbox/enrollment-command.ts    | 14 +++++++-
 8 files changed, 145 insertions(+), 18 deletions(-)
 create mode 100644 apps/web/src/features/sandbox/console-config.test.ts
 create mode 100644 apps/web/src/features/sandbox/console-config.ts

diff --git a/apps/web/e2e/sandbox-setup.spec.ts b/apps/web/e2e/sandbox-setup.spec.ts
index a94234d22..dc361a319 100644
--- a/apps/web/e2e/sandbox-setup.spec.ts
+++ b/apps/web/e2e/sandbox-setup.spec.ts
@@ -16,6 +16,35 @@ test.beforeEach(async ({ page, request }) => {
   await expect(page.getByRole("button", { name: "Sessions", exact: true })).toBeVisible();
 });
 
+test("bundled console needs no extra admin key and provides one install command with automatic node status", async ({ page, request }) => {
+  await page.route("**/console/config", (route) => route.fulfill({ contentType: "application/json", body: JSON.stringify({ sandbox_admin: true, node_installer: true, node_installer_sha256: "a".repeat(64) }) }));
+  const browserAuthorizations: Array<string | undefined> = [];
+  await page.route("**/core/v1/sandbox/**", async (route) => {
+    browserAuthorizations.push(route.request().headers().authorization);
+    await route.continue({ headers: { ...route.request().headers(), authorization: "Bearer fixture-admin-key" } });
+  });
+  await page.reload();
+  await page.getByRole("button", { name: "Hosted Sandbox Manager", exact: true }).click();
+  await expect(page.getByRole("heading", { name: "Set up hosted sandboxes" })).toBeVisible();
+  await expect(page.getByLabel("Deployment admin key")).toHaveCount(0);
+  await expect(page.getByLabel("Core origin reachable from nodes and guests")).toHaveValue(new URL(page.url()).origin);
+  await page.getByLabel("Sandbox provider").selectOption("docker");
+  await page.getByRole("button", { name: "Initialize sandbox deployment" }).click();
+  await page.getByRole("button", { name: "Generate node command" }).click();
+  const command = page.getByLabel("One-time enrollment command");
+  await expect(command).toHaveValue(/PARSAR_NODE_ENROLLMENT_TOKEN='fixture-once-token' python3 -c/);
+  await expect(command).toHaveValue(/\/node-install\/node_install.py/);
+  await expect(command).toHaveValue(/hashlib.sha256/);
+  await expect(page.getByRole("button", { name: "Copy node command" })).toBeVisible();
+  await expect(page.getByRole("status")).toContainText("refresh automatically");
+  await expect(page.locator(".sandbox-manager")).not.toContainText("Create a private /etc/parsar/sandbox-node.json");
+  await request.post(`${fixture}/__fixture/sandbox-add-node`);
+  await expect(page.getByRole("region", { name: "Sandbox nodes", exact: true })).toContainText("Enrolled host", { timeout: 10000 });
+  await expect(page.getByRole("region", { name: "Sandbox nodes", exact: true })).toContainText("Provider ready");
+  expect(browserAuthorizations.length).toBeGreaterThan(0);
+  expect(browserAuthorizations.every((value) => value === undefined)).toBe(true);
+});
+
 for (const provider of ["docker", "microsandbox"]) {
   test(`initial ${provider} setup, enrollment, refresh and immutable selection`, async ({ page, request }) => {
     await page.setViewportSize({ width: 390, height: 844 });
diff --git a/apps/web/src/features/sandbox/NodeEnrollment.tsx b/apps/web/src/features/sandbox/NodeEnrollment.tsx
index 56f8592cb..1cd5a7394 100644
--- a/apps/web/src/features/sandbox/NodeEnrollment.tsx
+++ b/apps/web/src/features/sandbox/NodeEnrollment.tsx
@@ -1,9 +1,11 @@
 import { useState } from "react";
 import type { SandboxDeployment } from "@agents-core-web/agents-client";
 import { sandboxCoreOrigin } from "./core-origin";
-import { enrollmentCommand } from "./enrollment-command";
+import type { SandboxConsoleConfig } from "./console-config";
+import { enrollmentCommand, nodeInstallCommand } from "./enrollment-command";
 
-export function NodeEnrollment({ deployment, initialCoreUrl, busy, enrollment, onEnroll, onClear }: {
+export function NodeEnrollment({ consoleConfig, deployment, initialCoreUrl, busy, enrollment, onEnroll, onClear }: {
+  consoleConfig: SandboxConsoleConfig | null;
   deployment: SandboxDeployment;
   initialCoreUrl: string;
   busy: boolean;
@@ -12,20 +14,37 @@ export function NodeEnrollment({ deployment, initialCoreUrl, busy, enrollment, o
   onClear: () => void;
 }) {
   const [commandUrl, setCommandUrl] = useState(initialCoreUrl);
+  const sourceUrl = sandboxCoreOrigin(window.location.origin);
+  const installer = consoleConfig?.node_installer && sourceUrl;
+  const [copied, setCopied] = useState(false);
+  const [copyFailed, setCopyFailed] = useState(false);
   const coreUrl = sandboxCoreOrigin(deployment.core_url || commandUrl);
+  const command = enrollment && coreUrl ? installer
+    ? nodeInstallCommand(enrollment.token, coreUrl, sourceUrl!, deployment.provider, deployment.installation_id, consoleConfig!.node_installer_sha256)
+    : enrollmentCommand(enrollment.token, coreUrl) : "";
+  async function copyCommand() {
+    try { await navigator.clipboard.writeText(command); setCopied(true); setCopyFailed(false); }
+    catch { setCopied(false); setCopyFailed(true); }
+  }
   return <section className="form-stack sandbox-enrollment" aria-labelledby="sandbox-enrollment-heading"><h2 id="sandbox-enrollment-heading">Add node</h2>
-    <ol className="sandbox-steps">
+    {installer ? <>
+      <p>Run one command on the Linux amd64 host you want to add. It installs the matched node program and runtime image, writes the configuration, registers this host, and starts its background service.</p>
+      <p>The host needs Python 3.9+, a systemd user session with lingering enabled, and {deployment.provider === "docker" ? "access to Docker at /var/run/docker.sock" : "KVM access and the microsandbox host libraries"}. Run as a non-root user. The host must reach this console to download its node program; the host and sandbox guests must also reach the Core origin below.</p>
+    </> : <ol className="sandbox-steps">
       <li>Install <code>parsar-sandbox-node</code> from the same Core release on a Linux host. {deployment.provider === "docker" ? "Prepare its local Docker Unix socket and pinned runtime image." : "Prepare KVM access and the qualified microsandbox runtime, helper and firmware."}</li>
       <li>Create a private <code>/etc/parsar/sandbox-node.json</code> provider configuration with provider <code>{deployment.provider}</code> and installation ID <code>{deployment.installation_id}</code>. Use this host’s own backend paths and image. <a href="https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md#register-a-host" target="_blank" rel="noreferrer">Node configuration guide</a></li>
       <li>Generate the command below. Adjust its absolute paths, node name and capacity, then execute it on that host. Keep its private state directory on persistent storage.</li>
       <li>Run the node under the host’s service supervisor. Refresh sandbox state here and check that the node is online and its provider is ready.</li>
-    </ol>
+    </ol>}
     <label className="field"><span>Core URL reachable from the node</span><input type="url" placeholder="https://core.example" value={deployment.core_url || commandUrl} onChange={(event) => setCommandUrl(event.target.value)} readOnly={Boolean(deployment.core_url)} disabled={busy || Boolean(enrollment)} /></label>
     <p>This Core origin must also be reachable from sandbox guests. Every added node uses this deployment’s {deployment.provider} provider.</p>
-    {!enrollment ? <button type="button" className="button primary" disabled={busy || !coreUrl} onClick={() => void onEnroll()}>Generate enrollment command</button> : <>
+    {!enrollment ? <button type="button" className="button primary" disabled={busy || !coreUrl} onClick={() => void onEnroll()}>{installer ? "Generate node command" : "Generate enrollment command"}</button> : <>
       <p>One-time enrollment token expires {new Date(enrollment.expires_at).toLocaleString()}. Save the command now; it is cleared when you leave this page.</p>
-      <label className="field"><span>One-time enrollment command</span><textarea readOnly rows={12} value={coreUrl ? enrollmentCommand(enrollment.token, coreUrl) : ""} onFocus={(event) => event.target.select()} spellCheck={false} /></label>
-      <button type="button" className="button" onClick={onClear}>Clear enrollment command</button>
+      <label className="field"><span>One-time enrollment command</span><textarea readOnly rows={12} value={command} onFocus={(event) => event.target.select()} spellCheck={false} /></label>
+      <p role="status">Connection and provider health refresh automatically every few seconds.</p>
+      <button type="button" className="button primary" onClick={() => void copyCommand()}>{copied ? "Copied" : "Copy node command"}</button>
+      {copyFailed ? <p role="alert">Select the command above and copy it manually.</p> : null}
+      <button type="button" className="button" onClick={() => { setCopied(false); setCopyFailed(false); onClear(); }}>Clear enrollment command</button>
     </>}
   </section>;
 }
diff --git a/apps/web/src/features/sandbox/SandboxManagerView.tsx b/apps/web/src/features/sandbox/SandboxManagerView.tsx
index 9a3857a7c..29f25461a 100644
--- a/apps/web/src/features/sandbox/SandboxManagerView.tsx
+++ b/apps/web/src/features/sandbox/SandboxManagerView.tsx
@@ -3,6 +3,8 @@ import { SandboxAdminClient, type InitializeSandboxDeployment, type SandboxAlloc
 import { sandboxAdminBaseUrl } from "./SandboxContext";
 import { SandboxDiagnostic } from "./SandboxDiagnostic";
 import { NodeHealth } from "./NodeHealth";
+import { isLocalProxyBaseUrl } from "../../lib/connection";
+import { sandboxConsoleConfig, type SandboxConsoleConfig } from "./console-config";
 import { SandboxSetup } from "./SandboxSetup";
 import { NodeEnrollment } from "./NodeEnrollment";
 import "./SandboxManagerView.css";
@@ -18,6 +20,16 @@ export function SandboxManagerView({ coreBaseUrl }: { coreBaseUrl: string }) {
 function SandboxAccess({ coreBaseUrl }: { coreBaseUrl: string }) {
   const [draft, setDraft] = useState("");
   const [credential, setCredential] = useState("");
+  const [consoleConfig, setConsoleConfig] = useState<SandboxConsoleConfig | null>(null);
+  const [checkingConsole, setCheckingConsole] = useState(isLocalProxyBaseUrl(coreBaseUrl));
+  useEffect(() => {
+    if (!isLocalProxyBaseUrl(coreBaseUrl)) return;
+    const controller = new AbortController();
+    void sandboxConsoleConfig(controller.signal).then((config) => {
+      if (!controller.signal.aborted) { setConsoleConfig(config); setCheckingConsole(false); }
+    });
+    return () => controller.abort();
+  }, [coreBaseUrl]);
   function connect(event: FormEvent) {
     event.preventDefault();
     if (draft.trim()) { setCredential(draft.trim()); setDraft(""); }
@@ -26,17 +38,17 @@ function SandboxAccess({ coreBaseUrl }: { coreBaseUrl: string }) {
     <header className="sandbox-heading"><div><h1>Hosted Sandbox Manager</h1><p>Deployment provider, runtime nodes and Session allocations.</p></div>
       {credential ? <button type="button" className="button" onClick={() => setCredential("")}>Disconnect admin</button> : null}
     </header>
-    {!credential ? <form className="form-stack sandbox-access" onSubmit={connect}>
+    {checkingConsole ? <p role="status">Connecting to this console’s Core…</p> : !credential && !consoleConfig?.sandbox_admin ? <form className="form-stack sandbox-access" onSubmit={connect}>
       <h2>Deployment administrator access</h2>
       <p>Enter the separate deployment admin key. It stays in memory until you leave this page or disconnect.</p>
       <label className="field"><span>Deployment admin key</span><input type="password" autoComplete="off" value={draft} onChange={(event) => setDraft(event.target.value)} required /></label>
       <button type="submit" className="button primary" disabled={!draft.trim()}>Connect admin</button>
-    </form> : <SandboxManager key={`${coreBaseUrl}:${credential}`} coreBaseUrl={coreBaseUrl} credential={credential} />}
+    </form> : <SandboxManager key={`${coreBaseUrl}:${credential}`} coreBaseUrl={coreBaseUrl} credential={credential} consoleConfig={consoleConfig} />}
   </section>;
 }
 
-function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; credential: string }) {
-  const client = useMemo(() => new SandboxAdminClient({ baseUrl: sandboxAdminBaseUrl(coreBaseUrl), token: credential }), [coreBaseUrl, credential]);
+function SandboxManager({ coreBaseUrl, credential, consoleConfig }: { coreBaseUrl: string; credential: string; consoleConfig: SandboxConsoleConfig | null }) {
+  const client = useMemo(() => new SandboxAdminClient({ baseUrl: sandboxAdminBaseUrl(coreBaseUrl), token: credential, fetch: (input, init) => fetch(input, { ...init, credentials: "include" }) }), [coreBaseUrl, credential]);
   const [snapshot, setSnapshot] = useState<{ deployment: SandboxDeployment; nodes: SandboxNode[]; allocations: SandboxAllocation[] } | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
@@ -44,7 +56,7 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
   const [revision, setRevision] = useState(0);
   const [removeId, setRemoveId] = useState<string | null>(null);
   const [enrollment, setEnrollment] = useState<{ token: string; expires_at: string } | null>(null);
-  const initialCoreUrl = coreBaseUrl.startsWith("http") ? coreBaseUrl.replace(/\/v1\/?$/, "") : "";
+  const initialCoreUrl = coreBaseUrl.startsWith("http") ? coreBaseUrl.replace(/\/v1\/?$/, "") : consoleConfig?.sandbox_admin ? window.location.origin : "";
   const [setupNeedsRefresh, setSetupNeedsRefresh] = useState(false);
   const lifetime = useRef<AbortController | null>(null);
   useEffect(() => {
@@ -65,6 +77,11 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
       .finally(() => { if (!controller.signal.aborted) setLoading(false); });
     return () => controller.abort();
   }, [client, revision]);
+  useEffect(() => {
+    if (!enrollment || busy) return;
+    const interval = window.setInterval(() => setRevision((value) => value + 1), 3000);
+    return () => window.clearInterval(interval);
+  }, [enrollment, busy]);
   async function initialize(input: InitializeSandboxDeployment) {
     const controller = lifetime.current;
     if (!controller || busy || loading || setupNeedsRefresh) return;
@@ -103,7 +120,7 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
   return <div className="form-stack">
     <div className="sandbox-toolbar"><button type="button" className="button" disabled={loading || busy} onClick={() => setRevision((v) => v + 1)}>Refresh sandbox state</button>{loading ? <span role="status">Loading sandbox state…</span> : busy ? <span role="status">Saving sandbox change…</span> : null}</div>
     {error ? <p role="alert" className="sandbox-error">{error}{snapshot ? " Previously loaded state is shown below." : ""}</p> : null}
-    {snapshot && !snapshot.deployment.provider ? <SandboxSetup key={revision} initialCoreUrl={initialCoreUrl} disabled={busy || loading || setupNeedsRefresh || Boolean(error)} onInitialize={initialize} /> : null}
+    {snapshot && !snapshot.deployment.provider ? <SandboxSetup automaticInstall={consoleConfig?.node_installer} key={revision} initialCoreUrl={initialCoreUrl} disabled={busy || loading || setupNeedsRefresh || Boolean(error)} onInitialize={initialize} /> : null}
     {snapshot?.deployment.provider ? <>
       <dl className="sandbox-summary">
         <div><dt>Provider</dt><dd>{snapshot.deployment.provider === "docker" ? "Docker" : "microsandbox"}</dd></div>
@@ -121,7 +138,7 @@ function SandboxManager({ coreBaseUrl, credential }: { coreBaseUrl: string; cred
           {snapshot.allocations.map((allocation) => <tr key={allocation.id}><td><code>{allocation.session_id}</code></td><td>{snapshot.nodes.find((node) => node.id === allocation.node_id)?.name ?? allocation.node_id}</td><td>{allocation.state}</td><td>{allocation.compute_phase}</td><td><SandboxDiagnostic diagnostic={allocation.diagnostic} />{!allocation.diagnostic ? "No reported issue" : null}</td></tr>)}
         </tbody></table></div> : <p>No sandbox allocations.</p>}
       </section>
-      <NodeEnrollment deployment={snapshot.deployment} initialCoreUrl={initialCoreUrl} busy={busy || loading || Boolean(error)} enrollment={enrollment} onEnroll={enroll} onClear={() => setEnrollment(null)} />
+      <NodeEnrollment consoleConfig={consoleConfig} deployment={snapshot.deployment} initialCoreUrl={initialCoreUrl} busy={busy || loading || Boolean(error)} enrollment={enrollment} onEnroll={enroll} onClear={() => setEnrollment(null)} />
     </> : null}
   </div>;
 }
diff --git a/apps/web/src/features/sandbox/SandboxSetup.tsx b/apps/web/src/features/sandbox/SandboxSetup.tsx
index a5af3a7a8..2b262db52 100644
--- a/apps/web/src/features/sandbox/SandboxSetup.tsx
+++ b/apps/web/src/features/sandbox/SandboxSetup.tsx
@@ -2,8 +2,9 @@ import { useState, type FormEvent } from "react";
 import type { InitializeSandboxDeployment, SandboxProvider } from "@agents-core-web/agents-client";
 import { sandboxCoreOrigin } from "./core-origin";
 
-export function SandboxSetup({ initialCoreUrl, disabled, onInitialize }: {
+export function SandboxSetup({ initialCoreUrl, automaticInstall = false, disabled, onInitialize }: {
   initialCoreUrl: string;
+  automaticInstall?: boolean;
   disabled: boolean;
   onInitialize: (input: InitializeSandboxDeployment) => Promise<void>;
 }) {
@@ -20,7 +21,7 @@ export function SandboxSetup({ initialCoreUrl, disabled, onInitialize }: {
     <label className="field"><span>Sandbox provider</span><select value={provider} onChange={(event) => setProvider(event.target.value as SandboxProvider)} disabled={disabled} required>
       <option value="" disabled>Choose a provider</option><option value="docker">Docker</option><option value="microsandbox">microsandbox</option>
     </select></label>
-    <p>{provider === "docker" ? "Docker nodes need a local Docker Unix socket and a pinned runtime image." : provider === "microsandbox" ? "microsandbox nodes need Linux with KVM, the qualified runtime, helper and firmware." : "Prepare a compatible host after selecting the provider."}</p>
+    <p>{provider === "docker" ? (automaticInstall ? "The host needs Docker access. The node command installs the matched runtime image." : "Docker nodes need a local Docker Unix socket and a pinned runtime image.") : provider === "microsandbox" ? (automaticInstall ? "The host needs Linux with KVM and the required host libraries. The node command installs the matched runtime, helper and firmware." : "microsandbox nodes need Linux with KVM, the qualified runtime, helper and firmware.") : "Prepare a compatible host after selecting the provider."}</p>
     <label className="field"><span>Core origin reachable from nodes and guests</span><input type="url" value={coreUrl} onChange={(event) => setCoreUrl(event.target.value)} placeholder="https://core.example" disabled={disabled} required aria-describedby="sandbox-core-origin-help" /></label>
     <p id="sandbox-core-origin-help">Use the Core API origin, reachable from every node and sandbox guest, without a path or credentials. Remote hosts require HTTPS; loopback HTTP is for local use only. The console URL may be different.</p>
     {coreUrl && !origin ? <p className="sandbox-error">Enter an HTTPS origin such as https://core.example, or a loopback HTTP origin for local use.</p> : null}
diff --git a/apps/web/src/features/sandbox/console-config.test.ts b/apps/web/src/features/sandbox/console-config.test.ts
new file mode 100644
index 000000000..e012dde17
--- /dev/null
+++ b/apps/web/src/features/sandbox/console-config.test.ts
@@ -0,0 +1,21 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { sandboxConsoleConfig } from "./console-config";
+
+afterEach(() => vi.unstubAllGlobals());
+describe("bundled console capabilities", () => {
+  it("uses the existing console login without sending a project or admin bearer", async () => {
+    const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify({ sandbox_admin: true, node_installer: true, node_installer_sha256: "a".repeat(64) })));
+    vi.stubGlobal("fetch", fetch);
+    const controller = new AbortController();
+    expect(await sandboxConsoleConfig(controller.signal)).toEqual({ sandbox_admin: true, node_installer: true, node_installer_sha256: "a".repeat(64) });
+    expect(fetch).toHaveBeenCalledWith("/console/config", { credentials: "include", signal: controller.signal });
+  });
+  it.each([{}, { sandbox_admin: "true", node_installer: true }, { sandbox_admin: false, node_installer: true, node_installer_sha256: "bad" }])("does not enable installation without a verified digest %j", async (body) => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(JSON.stringify(body))));
+    expect((await sandboxConsoleConfig(new AbortController().signal))?.node_installer).toBe(false);
+  });
+  it("falls back to direct credentials on an absent console capability endpoint", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("Not found", { status: 404 })));
+    expect(await sandboxConsoleConfig(new AbortController().signal)).toBeNull();
+  });
+});
diff --git a/apps/web/src/features/sandbox/console-config.ts b/apps/web/src/features/sandbox/console-config.ts
new file mode 100644
index 000000000..dc481ea49
--- /dev/null
+++ b/apps/web/src/features/sandbox/console-config.ts
@@ -0,0 +1,18 @@
+export interface SandboxConsoleConfig {
+  sandbox_admin: boolean;
+  node_installer: boolean;
+  node_installer_sha256: string;
+}
+
+export async function sandboxConsoleConfig(signal: AbortSignal): Promise<SandboxConsoleConfig | null> {
+  try {
+    const response = await fetch("/console/config", { credentials: "include", signal });
+    if (!response.ok) return null;
+    const config = await response.json() as Partial<SandboxConsoleConfig>;
+    return {
+      sandbox_admin: config.sandbox_admin === true,
+      node_installer: config.node_installer === true && /^[a-f0-9]{64}$/.test(config.node_installer_sha256 ?? ""),
+      node_installer_sha256: config.node_installer_sha256 ?? "",
+    };
+  } catch { return null; }
+}
diff --git a/apps/web/src/features/sandbox/enrollment-command.test.ts b/apps/web/src/features/sandbox/enrollment-command.test.ts
index adefc79dc..af808c70d 100644
--- a/apps/web/src/features/sandbox/enrollment-command.test.ts
+++ b/apps/web/src/features/sandbox/enrollment-command.test.ts
@@ -1,8 +1,18 @@
 import { describe, expect, it } from "vitest";
-import { enrollmentCommand } from "./enrollment-command";
+import { enrollmentCommand, nodeInstallCommand } from "./enrollment-command";
 import { sandboxAdminBaseUrl } from "./SandboxContext";
 
 describe("sandbox connection and enrollment", () => {
+  it("creates one node installer command with a verified same-release script and no credential argument", () => {
+    const command = nodeInstallCommand("secret'onetime", "https://core.example", "https://console.example", "docker", "installation", "a".repeat(64));
+    expect(command).toContain("PARSAR_NODE_ENROLLMENT_TOKEN='secret'\\''onetime' python3 -c");
+    expect(command).toContain("https://console.example/node-install/node_install.py");
+    expect(command).toContain("hashlib.sha256(code).hexdigest()");
+    expect(command).toContain("a".repeat(64));
+    expect(command).toContain("Installer redirects are not supported");
+    expect(command).toContain("--source-url 'https://console.example' --core-url 'https://core.example' --provider 'docker' --installation-id 'installation'");
+    expect(command).not.toContain("--enrollment-token");
+  });
   it("derives a separate admin prefix for local and prefixed remote Core deployments", () => {
     expect(sandboxAdminBaseUrl("/v1")).toBe("/core/v1/sandbox");
     expect(sandboxAdminBaseUrl("https://core.example/prefix/v1/")).toBe("https://core.example/prefix/core/v1/sandbox");
diff --git a/apps/web/src/features/sandbox/enrollment-command.ts b/apps/web/src/features/sandbox/enrollment-command.ts
index 58fd46053..64aeb4296 100644
--- a/apps/web/src/features/sandbox/enrollment-command.ts
+++ b/apps/web/src/features/sandbox/enrollment-command.ts
@@ -1,7 +1,19 @@
+const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+
+export function nodeInstallCommand(token: string, coreUrl: string, sourceUrl: string, provider: string, installationId: string, scriptDigest: string): string {
+  const bootstrap = `import hashlib, urllib.request
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+ def redirect_request(self, *args): raise RuntimeError("Installer redirects are not supported")
+with urllib.request.build_opener(NoRedirect()).open(${JSON.stringify(sourceUrl + "/node-install/node_install.py")}, timeout=30) as response:
+ code = response.read(1048577)
+if len(code) > 1048576 or hashlib.sha256(code).hexdigest() != ${JSON.stringify(scriptDigest)}: raise RuntimeError("Node installer checksum mismatch")
+exec(compile(code, "node_install.py", "exec"))`;
+  return `PARSAR_NODE_ENROLLMENT_TOKEN=${quote(token)} python3 -c ${quote(bootstrap)} --source-url ${quote(sourceUrl)} --core-url ${quote(coreUrl)} --provider ${quote(provider)} --installation-id ${quote(installationId)}`;
+}
+
 export function enrollmentCommand(token: string, coreUrl: string): string {
   let delimiter = "PARSAR_ENROLLMENT_TOKEN";
   while (token.split("\n").includes(delimiter)) delimiter += "_END";
-  const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
   return `umask 077
 mkdir -p /var/lib/parsar/sandbox-node
 cat > /var/lib/parsar/sandbox-node/enrollment-token <<'${delimiter}'

From 05534309543d16df6abdf8dbc1d5a031126f062c Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 20:50:13 +0800
Subject: [PATCH 6/9] feat(install): connect zero-node Core setup with paired
 console onboarding

---
 CONTRIBUTING.md                               |  31 +++-
 .../agents-api/sandbox-manager.openapi.yaml   |  52 +++++++
 deploy/install/configuration.py               |  19 ++-
 deploy/install/install.py                     |  51 +++++--
 deploy/install/test_install.py                |  50 +++++--
 docs/getting-started/install.md               |  67 +++++++--
 .../agentdaemon/gateway/bootstrap_url_test.go |  47 ++++++
 internal/agentdaemon/gateway/handler.go       |  13 +-
 scripts/build-core-distribution.sh            |   2 +-
 services/agents-api/HOSTED-SANDBOX-MANAGER.md |  78 ++++++++--
 services/agents-api/cmd/server/main.go        |  19 ++-
 .../agents-api/cmd/server/managed_nodes.go    |  26 +++-
 .../agents-api/cmd/server/managed_setup.go    |  96 ++++++++++++
 .../cmd/server/managed_setup_test.go          |  54 +++++++
 .../cmd/server/startup_configuration.go       |   2 +-
 .../agents-api/internal/runtime/gateway.go    |   9 +-
 services/core-console/config.go               |  14 ++
 services/core-console/node_installation.go    |  89 +++++++++++
 .../core-console/node_installation_test.go    | 141 ++++++++++++++++++
 services/core-console/sandbox_admin.go        |   4 +-
 services/core-console/server.go               |  62 +++++++-
 21 files changed, 851 insertions(+), 75 deletions(-)
 create mode 100644 internal/agentdaemon/gateway/bootstrap_url_test.go
 create mode 100644 services/agents-api/cmd/server/managed_setup.go
 create mode 100644 services/agents-api/cmd/server/managed_setup_test.go
 create mode 100644 services/core-console/node_installation.go
 create mode 100644 services/core-console/node_installation_test.go

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a1991aca5..127630a2d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -596,6 +596,33 @@ does not qualify its isolation or enable public creation.
 
 ### Hosted sandbox nodes and optional suspension
 
+Default installation includes Core, Web and PostgreSQL but no execution node.
+It always creates a separate deployment administrator credential. Core receives
+only its digest; the paired console server receives the private token and injects
+it only on approved management routes after console login and same-origin checks.
+The browser never receives that token. Node/daemon transport routes instead
+forward their own credentials unchanged to Core. Zero-node Core receives neither the Docker socket nor KVM.
+The Web's first setup selects one provider and public Core origin through the
+admin-only deployment endpoint. The paired console serves only an explicit list
+of non-secret matched distribution artifacts for its node installation command;
+never serve private installation files or arbitrary paths. Node installation
+reuses the existing node process and Provider configuration, verifies downloaded
+files, retains private identity and uses a user service. It performs no SSH
+installation, Session creation or model call. PostgreSQL owns this immutable selection under
+the existing execution lease and deployment lock. Exact retries are idempotent;
+a changed selection conflicts. No provider migration or hot reload is implied.
+
+Web-managed startup claims the stable installation identity and a new owner epoch
+even before provider selection. The existing runtime manager stays present and
+loads one immutable configuration when selection becomes available, before any
+node lifecycle is created. Admission refuses uninitialized hosted work without
+creating Session state. File-managed and Web-managed configuration are mutually
+exclusive. Node registration, observation and daemon bootstrap reuse existing
+contracts. Derive Runtime bootstrap and daemon WebSocket addresses from the saved
+validated origin; never infer them from inbound Host headers. Keep the startup
+configuration API a startup snapshot; use the live deployment endpoint in setup.
+
+
 A Core deployment may run without a sandbox provider. When enabled, exactly one
 sandbox provider is selected at setup: Docker or microsandbox. Keep both adapters but reject multiple provider entries,
 legacy default-provider maps and engine-based placement. Harness selection is
@@ -618,8 +645,8 @@ migrate an existing Session to another provider or recreate a released allocatio
 Fresh adoption of a deployment with unverified retained allocations fails closed.
 
 The [Hosted Sandbox Manager](services/agents-api/HOSTED-SANDBOX-MANAGER.md) is a
-deployment-level admin surface, separate from project credentials. Its Web token
-stays in memory. Node enrollment credentials authorize only registration; durable
+deployment-level admin surface, separate from project credentials. A direct-Core
+Web token stays in memory; the paired console token stays on its server. Node enrollment credentials authorize only registration; durable
 node credentials authorize only node transport. Project keys can read a narrow
 node directory and their own Session placement, never global allocations.
 
diff --git a/contracts/agents-api/sandbox-manager.openapi.yaml b/contracts/agents-api/sandbox-manager.openapi.yaml
index 61dfd8969..dfe112cda 100644
--- a/contracts/agents-api/sandbox-manager.openapi.yaml
+++ b/contracts/agents-api/sandbox-manager.openapi.yaml
@@ -34,6 +34,8 @@ definitions:
     type: object
   store.RuntimeDeploymentView:
     properties:
+      core_url:
+        type: string
       installation_id:
         type: string
       maintenance:
@@ -142,6 +144,13 @@ definitions:
       name:
         type: string
     type: object
+  store.SandboxDeploymentSetupRequest:
+    properties:
+      core_url:
+        type: string
+      provider:
+        type: string
+    type: object
   v1.APIError:
     properties:
       code:
@@ -213,6 +222,49 @@ paths:
       summary: Retrieve sandbox deployment
       tags:
         - Sandbox Manager
+    post:
+      consumes:
+        - application/json
+      description: Selects one immutable provider and public Core origin. Exact retries return the existing selection; differing selections and file-managed deployments reject. This does not create a node or execute work.
+      parameters:
+        - description: Deployment selection
+          in: body
+          name: body
+          required: true
+          schema:
+            $ref: '#/definitions/store.SandboxDeploymentSetupRequest'
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/store.RuntimeDeploymentView'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+      security:
+        - DeploymentAdminAuth: []
+      summary: Initialize the deployment sandbox provider once
+      tags:
+        - Sandbox Manager
   /core/v1/sandbox/enroll:
     post:
       consumes:
diff --git a/deploy/install/configuration.py b/deploy/install/configuration.py
index 6bb3589f3..747b3ac10 100644
--- a/deploy/install/configuration.py
+++ b/deploy/install/configuration.py
@@ -50,12 +50,14 @@ def core_environment(root, state, database_password):
         "AGENTS_API_ENGINE": "codex", "AGENTS_API_HARNESSES": "codex,claude_sdk,mcode",
         "AGENTS_API_DAEMON_WS_URL": f"ws://{daemon_host}/api/v1/agent-daemon/ws",
     }
+    result["AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE"] = (
+        str(Path(root) / "admin/digests.json") if native else "/admin/digests.json")
+    if not state["provider"]:
+        result["AGENTS_API_SANDBOX_INSTALLATION_ID"] = state["installation_id"]
     if state["provider"]:
         result["AGENTS_API_MANAGED_RUNTIMES_FILE"] = config + "/managed-runtimes.json"
         result["AGENTS_API_SANDBOX_NODE_STATE_DIR"] = (
             str(Path(root) / "state/sandbox-node") if native else "/state/sandbox-node")
-        result["AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE"] = (
-            str(Path(root) / "admin/digests.json") if native else "/admin/digests.json")
     return result
 
 
@@ -91,10 +93,10 @@ def compose_config(root, state, manifest, database_password):
             services["database"]["ports"] = [f'127.0.0.1:{state["database_port"]}:5432']
             services.pop("migrate")
         else:
+            core["volumes"].append(bind(root / "admin/digests.json", "/admin/digests.json"))
             if state["provider"] == "docker":
                 core["volumes"].append(bind("/var/run/docker.sock", "/var/run/docker.sock", False))
                 core["volumes"].append(bind(root / "state/sandbox-node", "/state/sandbox-node", False))
-                core["volumes"].append(bind(root / "admin/digests.json", "/admin/digests.json"))
                 core["group_add"] = [str(state["device_gid"])]
                 core["networks"] = ["default", "runtime"]
                 doc["networks"] = {"runtime": {"name": state["project"] + "-runtime"}}
@@ -107,12 +109,21 @@ def compose_config(root, state, manifest, database_password):
             "security_opt": ["no-new-privileges:true"],
             "volumes": [bind(config / "caller.key", "/config/caller.key"),
                         bind(config / "console.password", "/config/console.password")],
-            "environment": {"CORE_CONSOLE_ORIGIN": f'http://127.0.0.1:{state["web_port"]}',
+            "environment": {"CORE_CONSOLE_ORIGIN": state.get("public_url") or f'http://127.0.0.1:{state["web_port"]}',
                 "CORE_CONSOLE_UPSTREAM": (f'http://127.0.0.1:{state["core_port"]}' if native
                                           else state.get("core_url") or "http://core:8091"),
                 "CORE_CONSOLE_TOKEN_FILE": "/config/caller.key",
                 "CORE_CONSOLE_PASSWORD_FILE": "/config/console.password"},
         }
+        if state["mode"] == "all":
+            services["web"]["volumes"].extend([
+                bind(root / "admin/sandbox-admin.key", "/admin/sandbox-admin.key"),
+                bind(root / "node-payload", "/node-payload"),
+            ])
+            services["web"]["environment"].update(
+                CORE_CONSOLE_SANDBOX_ADMIN_TOKEN_FILE="/admin/sandbox-admin.key",
+                CORE_CONSOLE_NODE_PAYLOAD_DIR="/node-payload",
+            )
         if state["mode"] == "web-only" or native:
             services["web"].pop("ports")
             services["web"]["network_mode"] = "host"
diff --git a/deploy/install/install.py b/deploy/install/install.py
index 0015203f8..6ba42e676 100644
--- a/deploy/install/install.py
+++ b/deploy/install/install.py
@@ -8,6 +8,7 @@
 from pathlib import Path
 import platform
 import secrets
+import shutil
 import socket
 import stat
 import subprocess
@@ -15,6 +16,7 @@
 import time
 import urllib.error
 import urllib.request
+from urllib.parse import urlsplit
 import uuid
 
 from configuration import compose_config, core_environment, managed_config
@@ -60,7 +62,7 @@ def verify_bundle(bundle):
             raise InstallError("Invalid distribution path")
         if digest(path) != expected:
             raise InstallError("Distribution checksum mismatch: " + name)
-    required = {"manifest.json", "install.sh", "install.py", "configuration.py", "native_service.py", "runtime/seccomp.json"}
+    required = {"manifest.json", "install.sh", "install.py", "configuration.py", "native_service.py", "node_install.py", "runtime/seccomp.json"}
     required.update(f"images/{name}.tar" for name in ("core", "web", "runtime", "database"))
     required.update("native/bin/" + name for name in ("agents-api", "agents-api-migrate", "agents-api-microsandbox-provider", "parsar-sandbox-node"))
     required.update("native/microsandbox/" + name for name in ("msb", "libkrunfw.so.5.6.1"))
@@ -111,6 +113,7 @@ def arguments(argv=None):
     parser.add_argument("--core-port", type=int, default=8091)
     parser.add_argument("--web-port", type=int, default=8080)
     parser.add_argument("--core-url", type=core_target)
+    parser.add_argument("--public-url", type=core_target, help="Public HTTPS Core/Web origin behind your TLS reverse proxy")
     parser.add_argument("--core-token-file", type=Path)
     parser.add_argument("--status", action="store_true", help="Read installation health; never invoke a model")
     parser.add_argument("--stop", action="store_true", help="Stop installed services; retain all data")
@@ -186,8 +189,8 @@ def initialize(root, args, manifest):
     mode = "core-only" if args.core_only else "web-only" if args.web_only else "all"
     if (root / "installation.json").exists():
         state = json.loads((root / "installation.json").read_text())
-        wanted = (mode, args.provider, args.core_port, args.web_port, args.core_url)
-        actual = (state["mode"], state["provider"], state["core_port"], state["web_port"], state.get("core_url"))
+        wanted = (mode, args.provider, args.core_port, args.web_port, args.core_url, args.public_url)
+        actual = (state["mode"], state["provider"], state["core_port"], state["web_port"], state.get("core_url"), state.get("public_url"))
         if wanted != actual or state["source_commit"] != manifest["source_commit"]:
             raise InstallError("Existing installation differs; preserve it and follow the upgrade/provider-change guide")
         return state
@@ -213,8 +216,10 @@ def initialize(root, args, manifest):
     root.mkdir(mode=0o700, parents=True, exist_ok=True)
     os.chmod(root, 0o700)
     directories = ["config"]
+    if mode != "web-only":
+        directories.append("admin")
     if args.provider:
-        directories.extend(("state", "state/sandbox-node", "admin"))
+        directories.extend(("state", "state/sandbox-node"))
     if args.provider == "microsandbox":
         directories.append("state/msb")
     for name in directories:
@@ -222,7 +227,7 @@ def initialize(root, args, manifest):
     state = {"version": 1, "source_commit": manifest["source_commit"], "mode": mode,
              "provider": args.provider, "installation_id": str(uuid.uuid4()),
              "project": "parsar-" + secrets.token_hex(5), "uid": os.getuid(), "gid": os.getgid(),
-             "core_port": args.core_port, "web_port": args.web_port, "core_url": args.core_url}
+             "core_port": args.core_port, "web_port": args.web_port, "core_url": args.core_url, "public_url": args.public_url}
     if native_service.is_native(state):
         state["database_port"] = database_port()
     config = root / "config"
@@ -234,10 +239,10 @@ def initialize(root, args, manifest):
             "token_sha256": hashlib.sha256(token.encode()).hexdigest()}])
         private_write(config / "credential.key", base64.b64encode(secrets.token_bytes(32)).decode())
         private_write(config / "database.password", secrets.token_hex(32))
+        admin_token = secrets.token_hex(32)
+        private_write(root / "admin/sandbox-admin.key", admin_token)
+        write_json(root / "admin/digests.json", [hashlib.sha256(admin_token.encode()).hexdigest()])
         if args.provider:
-            admin_token = secrets.token_hex(32)
-            private_write(root / "admin/sandbox-admin.key", admin_token)
-            write_json(root / "admin/digests.json", [hashlib.sha256(admin_token.encode()).hexdigest()])
             write_json(config / "managed-runtimes.json", managed_config(root, state, manifest))
     private_write(config / "caller.key", token)
     if mode != "core-only":
@@ -248,6 +253,26 @@ def initialize(root, args, manifest):
     return state
 
 
+def prepare_node_payload(root, state, bundle):
+    if state["mode"] != "all":
+        return
+    destination = root / "node-payload"
+    # Public distribution files only. Never copy the private installation config.
+    names = ("node_install.py", "manifest.json", "SHA256SUMS", "images/runtime.tar",
+             "runtime/seccomp.json", "native/bin/parsar-sandbox-node",
+             "native/bin/agents-api-microsandbox-provider", "native/microsandbox/msb",
+             "native/microsandbox/libkrunfw.so.5.6.1")
+    for name in names:
+        source, target = bundle / name, destination / name
+        target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if target.exists():
+            if target.is_symlink() or not target.is_file() or digest(target) != digest(source):
+                raise InstallError("Installed node payload differs; preserve it and inspect the distribution")
+        else:
+            shutil.copyfile(source, target)
+            target.chmod(0o600)
+
+
 def import_runtime(root, state, manifest, bundle):
     if not native_service.is_native(state):
         return
@@ -284,6 +309,7 @@ def main(argv=None):
     if args.provider == "microsandbox" and not args.web_only:
         native_service.preflight(bundle)
     state = initialize(root, args, manifest)
+    prepare_node_payload(root, state, bundle)
     if state["provider"] == "docker":
         seccomp = bundle / "runtime/seccomp.json"
         if not (root / "config/seccomp.json").exists():
@@ -313,18 +339,19 @@ def main(argv=None):
     if state["mode"] != "core-only":
         url = f'http://127.0.0.1:{state["web_port"]}'
         auth = base64.b64encode(("admin:" + (root / "config/console.password").read_text()).encode()).decode()
-        if not wait_http(url + "/v1/agents", {"Authorization": "Basic " + auth, "OpenAI-Beta": "agents=v1"}):
+        if not wait_http(url + "/v1/agents", {"Authorization": "Basic " + auth, "OpenAI-Beta": "agents=v1",
+                "Host": urlsplit(state.get("public_url") or url).netloc}):
             raise InstallError("Web could not authenticate to Core. Inspect private configuration; no model was called")
-        print("Console: " + url + " (user: admin)")
+        print("Console: " + (state.get("public_url") or url) + " (user: admin)")
         print("Console password file: " + str(root / "config/console.password"))
     if state["mode"] != "web-only":
         print(f'API: http://127.0.0.1:{state["core_port"]}/v1')
         print("Caller key file: " + str(root / "config/caller.key"))
         if state["provider"]:
             print("Provider: " + state["provider"] + ". Runtime image prepared; Core provisions Sessions on demand.")
-            print("Sandbox administrator key file: " + str(root / "admin/sandbox-admin.key"))
         else:
-            print("No local sandbox provider configured. No execution node was installed.")
+            print("No execution node installed. Open Hosted Sandbox Manager to choose a provider and add nodes.")
+        print("Sandbox administrator key file: " + str(root / "admin/sandbox-admin.key"))
     print("Services installed. No model request was made. See docs/getting-started/quickstart.md.")
 
 
diff --git a/deploy/install/test_install.py b/deploy/install/test_install.py
index 3e6b463ab..96b124c62 100644
--- a/deploy/install/test_install.py
+++ b/deploy/install/test_install.py
@@ -83,7 +83,7 @@ def bundle(self):
         (bundle / "runtime").mkdir()
         (bundle / "manifest.json").write_text(json.dumps(self.manifest))
         (bundle / "runtime/seccomp.json").write_text('{"defaultAction":"SCMP_ACT_ERRNO"}')
-        for name in ("install.py", "configuration.py", "native_service.py", "install.sh"):
+        for name in ("install.py", "configuration.py", "native_service.py", "node_install.py", "install.sh"):
             shutil.copyfile(Path(__file__).with_name(name), bundle / name)
         for name in self.manifest["images"]:
             (bundle / "images" / (name + ".tar")).write_bytes(("synthetic " + name).encode())
@@ -102,6 +102,22 @@ def write_checksums(bundle):
             hashlib.sha256(path.read_bytes()).hexdigest() + "  " + str(path.relative_to(bundle)) + "\n"
             for path in files))
 
+    def test_node_payload_exports_only_matched_distribution_files(self):
+        state = self.initialize()
+        bundle = self.bundle()
+        install.prepare_node_payload(self.root, state, bundle)
+        payload = self.root / "node-payload"
+        exported = {str(path.relative_to(payload)) for path in payload.rglob("*") if path.is_file()}
+        self.assertEqual(len(exported), 9)
+        self.assertNotIn("config/caller.key", exported)
+        self.assertNotIn("admin/sandbox-admin.key", exported)
+        for name in exported:
+            self.assertEqual((payload / name).read_bytes(), (bundle / name).read_bytes())
+        install.prepare_node_payload(self.root, state, bundle)
+        (payload / "node_install.py").write_text("changed")
+        with self.assertRaises(install.InstallError):
+            install.prepare_node_payload(self.root, state, bundle)
+
     def test_repeat_installation_preserves_execution_identity_and_all_secrets(self):
         first = self.initialize()
         keys = self.document("config/keys.json")
@@ -209,10 +225,11 @@ def test_local_node_identity_has_persistent_private_state_only_on_core(self):
                             self.assertTrue(mount["read_only"])
 
     def test_sandbox_admin_credential_is_separate_and_belongs_only_to_core(self):
-        for provider in ("docker", "microsandbox"):
+        for provider in (None, "docker", "microsandbox"):
             with self.subTest(provider=provider):
-                self.root = self.work / ("admin-" + provider)
-                state = self.initialize("--sandbox-provider", "true", "--provider", provider)
+                self.root = self.work / ("admin-" + str(provider))
+                flags = ("--sandbox-provider", "true", "--provider", provider) if provider else ()
+                state = self.initialize(*flags)
                 admin = self.root / "admin"
                 token = (admin / "sandbox-admin.key").read_text()
                 self.assertEqual(self.document("admin/digests.json"), [hashlib.sha256(token.encode()).hexdigest()])
@@ -222,20 +239,21 @@ def test_sandbox_admin_credential_is_separate_and_belongs_only_to_core(self):
                 for path in admin.iterdir():
                     self.assertEqual(stat.S_IMODE(path.stat().st_mode), 0o600)
                 before = self.snapshot()
-                self.initialize("--sandbox-provider", "true", "--provider", provider)
+                self.initialize(*flags)
                 self.assertEqual(self.snapshot(), before)
                 environment = install.core_environment(self.root, state, "synthetic database password")
                 expected = str(admin / "digests.json") if provider == "microsandbox" else "/admin/digests.json"
                 self.assertEqual(environment["AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE"], expected)
                 for name, service in self.document("compose.json")["services"].items():
                     mounts = [m for m in service.get("volumes", []) if isinstance(m, dict) and m["target"].startswith("/admin")]
-                    self.assertEqual(len(mounts), 1 if name == "core" else 0)
+                    self.assertEqual(len(mounts), 1 if name in ("core", "web") else 0)
                     if mounts:
-                        self.assertEqual(mounts[0]["source"], str(admin / "digests.json"))
-                        self.assertEqual(mounts[0]["target"], "/admin/digests.json")
+                        filename = "digests.json" if name == "core" else "sandbox-admin.key"
+                        self.assertEqual(mounts[0]["source"], str(admin / filename))
+                        self.assertEqual(mounts[0]["target"], "/admin/" + filename)
                         self.assertTrue(mounts[0]["read_only"])
                     for mount in service.get("volumes", []):
-                        if isinstance(mount, dict):
+                        if isinstance(mount, dict) and name != "web":
                             source = Path(mount["source"])
                             self.assertFalse((admin / "sandbox-admin.key").is_relative_to(source))
                     if name != "core":
@@ -341,11 +359,12 @@ def test_default_has_no_provider_authority_or_runtime_configuration(self):
         self.assertEqual(self.device_probes, [])
         self.assertNotIn("device_gid", state)
         self.assertFalse((self.root / "state").exists())
-        self.assertFalse((self.root / "admin").exists())
+        self.assertTrue((self.root / "admin/digests.json").is_file())
         self.assertFalse((self.root / "config/managed-runtimes.json").exists())
         compose = self.document("compose.json")
         self.assertEqual(set(compose["services"]), {"database", "migrate", "core", "web"})
         self.assertNotIn("networks", compose)
+        self.assertEqual(compose["services"]["core"]["environment"]["AGENTS_API_SANDBOX_INSTALLATION_ID"], state["installation_id"])
         for service in compose["services"].values():
             self.assertNotIn("devices", service)
             self.assertNotIn("group_add", service)
@@ -353,6 +372,15 @@ def test_default_has_no_provider_authority_or_runtime_configuration(self):
             self.assertNotIn("AGENTS_API_MANAGED_RUNTIMES_FILE", service.get("environment", {}))
             self.assertNotIn("AGENTS_API_SANDBOX_NODE_STATE_DIR", service.get("environment", {}))
 
+    def test_public_origin_is_explicit_and_preserved(self):
+        state = self.initialize("--public-url", "https://core.example")
+        web = self.document("compose.json")["services"]["web"]
+        self.assertEqual(web["environment"]["CORE_CONSOLE_ORIGIN"], "https://core.example")
+        self.assertEqual(web["ports"], ["127.0.0.1:8080:8080"])
+        self.assertEqual(state["public_url"], "https://core.example")
+        with self.assertRaises(install.InstallError):
+            self.initialize("--public-url", "https://other.example")
+
     def test_provider_requires_explicit_enablement_and_cannot_belong_to_web_only(self):
         self.assertIsNone(self.args("--sandbox-provider", "false").provider)
         self.assertEqual(self.args("--sandbox-provider").provider, "microsandbox")
@@ -380,7 +408,7 @@ def test_default_main_skips_kvm_native_service_and_runtime_import(self):
                          [str(bundle / ("images/" + name + ".tar")) for name in ("core", "database", "web")])
         self.assertFalse((self.root / "native").exists())
         self.assertFalse((self.root / "config/seccomp.json").exists())
-        self.assertIn("No execution node was installed", output.getvalue())
+        self.assertIn("No execution node installed", output.getvalue())
 
     def test_main_web_only_never_imports_runtime_or_leaks_caller_password(self):
         source = self.caller_file()
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 4d7aa2f70..777c9743c 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -55,12 +55,13 @@ and Core service image; packaging it does not start or register a node.
 
 Installation creates private configuration under `~/.parsar/core`, a dedicated
 PostgreSQL volume, an API caller key and a credential encryption key. It also
-creates a separate console password. Secret values are not printed. On success:
+creates a separate console password and deployment administrator key. Secret values are not printed. On success:
 
 - API: `http://127.0.0.1:8091/v1`
 - Web console: `http://127.0.0.1:8080`, username `admin`
 - Console password file: `~/.parsar/core/config/console.password`
 - API caller key file: `~/.parsar/core/config/caller.key`
+- Sandbox administrator key file: `~/.parsar/core/admin/sandbox-admin.key`
 
 Use exactly the displayed console address; the production proxy validates its
 configured browser origin. The console password authenticates to the Web server;
@@ -91,17 +92,44 @@ writable in addition to its selected socket; `config` remains read-only.
 Native Core uses the same persistent directory directly. The default zero-node
 installation creates neither this state directory nor its mount.
 
-Opting in also creates a separate private deployment administrator key at
+Every Core installation creates a separate private deployment administrator key at
 `admin/sandbox-admin.key`. Core loads its SHA-256 digest from
 `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE`. Only the Core container mounts the
-digest file read-only; the raw administrator key remains on the host. The console
-and migration service receive neither file. Use this administrator key only for
-the Hosted Sandbox Manager's separate administration surface, never as the
-project caller key. Values are not printed. Default zero-node installation
-configures neither a sandbox provider nor sandbox administrator access; it remains
-a read-capable Core installation. Remote node enrollment requires an explicit
-managed deployment configuration and administrator setup, as described in the
-[Hosted Sandbox Manager guide](https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md).
+digest file read-only. The bundled Web server reads the separate administrator
+key to proxy authenticated console operations; it never sends this key to the
+browser. The migration service receives neither. A Web-only connection to an
+external Core still requires its separate administrator key.
+
+### Add nodes after a default installation
+
+1. Log in to the bundled Web console and open **Hosted Sandbox Manager**.
+   The paired installation needs no second key or Core connection setup.
+2. Choose Docker or microsandbox and enter the HTTPS Core origin reachable from
+   both node hosts and their sandbox guests. The address must expose Core's API
+   and WebSocket routes, not just the Web console. HTTP loopback is available for
+   local development only; loopback inside a sandbox is not the Core host.
+3. Save the selection. It takes effect without restarting Core and remains in
+   PostgreSQL across restarts. All nodes in this deployment use the chosen type;
+   this page does not switch providers. Microsandbox uses a five-minute idle
+   timeout and one-day snapshot retention.
+4. Generate and copy the node command, then run it as a non-root user on the
+   target Linux amd64 host. It downloads the matched files from your console,
+   verifies checksums, imports the Runtime image, writes the provider configuration,
+   registers the node and starts a systemd user service. Web refreshes node health
+   automatically. A registered but unavailable node cannot accept work.
+
+The target host needs Python 3.9+, a systemd user session with lingering enabled,
+and either Docker socket access or microsandbox's KVM/native-library prerequisites.
+The command reports unmet prerequisites before downloading the Runtime.
+The console serves only fixed, non-secret distribution files at `/node-install/`;
+private installation configuration is never part of this payload. Retain the
+installed `node-payload/` directory.
+
+See the [Hosted Sandbox Manager guide](https://github.com/MiniMax-AI/parsar-core/blob/main/services/agents-api/HOSTED-SANDBOX-MANAGER.md)
+for host prerequisites and the registration command. The browser does not install
+software on another machine or receive SSH credentials. Adding a remote node does
+not add a Docker socket or KVM permissions to Core. Node installation and Runtime
+storage remain on the selected host.
 
 When a Session needs a sandbox, Core asks the
 enabled Provider to create one from the prepared Runtime image and initializes
@@ -131,15 +159,26 @@ revision changes on an existing installation. This includes enabling a sandbox
 provider on an installation originally created without one; rerunning with new
 flags does not migrate it.
 
-For remote browser or SDK access, put the intended endpoint behind your existing
-TLS and access-control boundary. Update the console's trusted origin explicitly;
-do not simply publish its port on every network interface.
+For remote nodes, install with the intended shared HTTPS endpoint:
+
+```sh
+./install.sh --public-url https://core.example
+```
+
+Configure your TLS reverse proxy to forward that origin to the loopback Web port,
+preserve Host, and support WebSocket upgrades. The bundled Web forwards the fixed
+node and daemon transport routes to Core using their own credentials. Both the
+node host and its sandbox guests must reach this address. Installation does not
+create DNS records or certificates, nor expose a host port publicly. Without this
+option, the console uses its loopback address for local access. Do not copy a
+localhost download command to a different machine.
 
 ## After installation
 
 Start with an optional [API request](quickstart.md). The read-only example works
 with the default installation. The execution example requires an installation
-created with a sandbox provider enabled. Session creation supplies the model,
+with a connected, ready sandbox node, either installed locally or added through
+Web. Session creation supplies the model,
 harness and write-only model credentials. Core owns sandbox preparation and
 Runtime startup. Configuration is never injected into a public Agent instruction
 or baked into a Runtime image.
diff --git a/internal/agentdaemon/gateway/bootstrap_url_test.go b/internal/agentdaemon/gateway/bootstrap_url_test.go
new file mode 100644
index 000000000..db4b22c65
--- /dev/null
+++ b/internal/agentdaemon/gateway/bootstrap_url_test.go
@@ -0,0 +1,47 @@
+package gateway
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/MiniMax-AI-Dev/parsar/internal/agentdaemon/device"
+)
+
+func TestBootstrapResolvesPublicURLOnlyAfterAuthentication(t *testing.T) {
+	const token = "synthetic-bootstrap-credential"
+	for _, tc := range []struct {
+		name, bearer, result string
+		err                  error
+		status, calls        int
+	}{
+		{"selected origin", token, "wss://core.example/api/v1/agent-daemon/ws", nil, 200, 1},
+		{"unavailable", token, "", errors.New("private database detail"), 503, 1},
+		{"empty origin", token, "", nil, 503, 1},
+		{"unauthenticated", "wrong", "", nil, 401, 0},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			calls := 0
+			h := NewHandler(HandlerConfig{Registry: NewRegistry(), PublicWSURL: "ws://private-core:8091/api/v1/agent-daemon/ws",
+				Authenticator:      NewAuthenticator(&stubRuntimeStore{ok: true, row: device.Credential{ID: "device", WorkspaceID: "tenant", Type: RuntimeTypeAgentDaemon, CredentialHash: device.HashCredential(token)}}),
+				ResolvePublicWSURL: func(context.Context) (string, error) { calls++; return tc.result, tc.err },
+			})
+			r := httptest.NewRequest(http.MethodPost, "/agent-daemon/bootstrap", strings.NewReader(`{"device_id":"device"}`))
+			r.Header.Set("Authorization", "Bearer "+tc.bearer)
+			w := httptest.NewRecorder()
+			h.Bootstrap(w, r)
+			if w.Code != tc.status || calls != tc.calls {
+				t.Fatalf("status %d, calls %d", w.Code, calls)
+			}
+			if strings.Contains(w.Body.String(), "private-") || strings.Contains(w.Body.String(), "private database detail") {
+				t.Fatalf("private configuration leaked: %s", w.Body.String())
+			}
+			if tc.status == 200 && !strings.Contains(w.Body.String(), tc.result) {
+				t.Fatalf("selected address missing: %s", w.Body.String())
+			}
+		})
+	}
+}
diff --git a/internal/agentdaemon/gateway/handler.go b/internal/agentdaemon/gateway/handler.go
index a55214df7..b1db3f6f6 100644
--- a/internal/agentdaemon/gateway/handler.go
+++ b/internal/agentdaemon/gateway/handler.go
@@ -41,6 +41,9 @@ type HandlerConfig struct {
 	// response so deployments behind a TLS terminator can advertise
 	// the externally-reachable URL.
 	PublicWSURL string
+	// ResolvePublicWSURL reads a deployment's configured public endpoint after
+	// authentication. A failure must not fall back to an unreachable private URL.
+	ResolvePublicWSURL func(context.Context) (string, error)
 
 	// OwnerStore enables multi-pod WebSocket ownership. When set, every
 	// successful daemon WS dial-in claims device_id -> owner_pod_id in
@@ -236,10 +239,18 @@ func (h *Handler) Bootstrap(w http.ResponseWriter, r *http.Request) {
 		writeAuthError(w, status, code, err.Error())
 		return
 	}
+	wsURL := h.cfg.PublicWSURL
+	if h.cfg.ResolvePublicWSURL != nil {
+		wsURL, err = h.cfg.ResolvePublicWSURL(r.Context())
+		if err != nil || wsURL == "" {
+			writeAuthError(w, http.StatusServiceUnavailable, "bootstrap_unavailable", "Runtime connection address is unavailable")
+			return
+		}
+	}
 	resp := map[string]any{
 		"device_id":         auth.DeviceID,
 		"workspace_id":      auth.WorkspaceID,
-		"ws_url":            h.cfg.PublicWSURL,
+		"ws_url":            wsURL,
 		"heartbeat_seconds": int(h.cfg.HeartbeatInterval.Seconds()),
 		"protocol_version":  proto.Version,
 	}
diff --git a/scripts/build-core-distribution.sh b/scripts/build-core-distribution.sh
index f0e705f65..fb9587e12 100755
--- a/scripts/build-core-distribution.sh
+++ b/scripts/build-core-distribution.sh
@@ -74,7 +74,7 @@ if [[ "$(go env GOVERSION)" != "$required_go" ]]; then
   printf 'Distribution build requires %s\n' "$required_go" >&2
   exit 1
 fi
-for file in install.sh install.py configuration.py native_service.py; do
+for file in install.sh install.py configuration.py native_service.py node_install.py; do
   cp "deploy/install/$file" "$bundle/$file"
 done
 mkdir -p "$bundle/docs"
diff --git a/services/agents-api/HOSTED-SANDBOX-MANAGER.md b/services/agents-api/HOSTED-SANDBOX-MANAGER.md
index bda67b1d8..3287cf840 100644
--- a/services/agents-api/HOSTED-SANDBOX-MANAGER.md
+++ b/services/agents-api/HOSTED-SANDBOX-MANAGER.md
@@ -6,22 +6,53 @@ Linux hosts. The deployment selects exactly one provider: `docker` or
 are distinct from user-managed `self_hosted` Environments, whose provisioning
 remains the user's responsibility.
 
-The Web console's **Hosted Sandbox Manager** page uses a separate deployment
-administrator credential. A project API key cannot register, edit or remove
-nodes, or list another project's allocations. The administrator credential is
-kept only in the page's memory. Re-enter it after a reload. Do not put it in the
-normal project connection settings or a URL.
-
-The distribution installer creates a separate administrator key under the private
-installation `admin/` directory when a local provider is enabled. It gives Core
-only the digest configuration; the console does not receive that key. Enter the
-key on this page after the ordinary console login. The production console forwards
-only sandbox administration requests with this explicit credential. Remote nodes
-must use the Core API origin for enrollment and connection, not the console URL.
-Default zero-node installation leaves sandbox administration unconfigured; use the
-explicit Core configuration below for an advanced remote-only deployment.
-
-## Configure Core
+The Web console's **Hosted Sandbox Manager** page uses deployment administrator
+authority, separate from project credentials. In a paired distribution, the
+console server reads its own administrator key and forwards it only on sandbox
+management routes after console login. No administrator key reaches the browser.
+Direct Core and Web-only connections still require an explicit administrator
+credential, retained only in page memory.
+
+The installer creates the separate key under the private `admin/` directory,
+including zero-node installs. Core receives its digest; the bundled Web server
+receives the original private key. Neither is included in static assets or the
+node installation payload. Project keys cannot register, edit or remove nodes.
+
+## Start with zero nodes
+
+Default installation starts Core, Web and PostgreSQL without local compute.
+Hosted Sandbox Manager first asks for Docker or microsandbox and the public HTTPS
+Core origin reachable from node hosts and sandbox guests. Use Core's origin, not
+the Web console URL; the proxy must forward API routes and WebSocket upgrades.
+HTTP loopback is accepted only for local development. A guest's loopback address
+cannot reach its Core host.
+
+Saving initializes the deployment once. An identical request may be retried;
+a different provider or origin returns a conflict. Refresh after an uncertain
+response before trying again. Selection persists in PostgreSQL, activates without
+a restart and applies to every node. Removing all nodes does not reset it.
+Microsandbox suspends eligible idle Sessions after 300 seconds and retains their
+snapshots for 86400 seconds. Docker has no memory snapshot policy.
+
+Generate and copy the node installation command and run it on the target Linux
+amd64 host. The installer checks prerequisites, downloads the matched payload,
+checks its hashes, prepares provider configuration and starts the existing node
+program as a systemd user service. Web polls readiness and capacity while waiting.
+It does not install software through SSH. Registration itself
+does not create a Session, sandbox or model request. Hosted Session admission
+fails until setup is complete and a ready node has capacity.
+
+For manual zero-node deployments, set `AGENTS_API_SANDBOX_INSTALLATION_ID` to a
+stable UUID, configure `AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE`, and enable the daemon
+gateway using `AGENTS_API_DAEMON_WS_URL`. Do not also set
+`AGENTS_API_MANAGED_RUNTIMES_FILE`. The Web-selected origin supplies hosted Runtime
+bootstrap and its public daemon WebSocket address; it never uses request Host or
+forwarded headers. Preserve the installation UUID and database together.
+
+The startup configuration API remains a startup snapshot. Use the live sandbox
+deployment response for a selection made after startup.
+
+## Configure a local or file-managed deployment
 
 Keep the existing `AGENTS_API_MANAGED_RUNTIMES_FILE` JSON. Existing Docker and
 microsandbox configurations participate through an embedded local node, using
@@ -96,6 +127,21 @@ do not extend snapshot retention.
 
 ## Register a host
 
+The paired console provides a complete installation command. It downloads only
+fixed public distribution artifacts from `/node-install/`; the enrollment token
+is transient and never a console/project credential. Python 3.9+, a systemd user
+session with lingering, and Docker access or KVM/native-library prerequisites
+must already exist on the target host. Rerunning the same command preserves the
+node's private identity; changes to its Core, installation, provider or release
+are refused. Use a newly generated token if an unconsumed one expires.
+
+For a public paired endpoint, use `install.sh --public-url https://core.example`
+and an operator-managed TLS reverse proxy preserving Host and WebSocket Upgrade.
+The console passes node and daemon credentials unchanged on a fixed route list;
+Core authenticates them. No administrator credential is used on these routes.
+Manual registration remains available for operator-managed payloads:
+
+
 Build/install `parsar-sandbox-node` from the same Core release. On the host,
 provide a private node provider JSON using the existing Docker or microsandbox
 backend schema. Match Core's provider and installation UUID; use that host's
diff --git a/services/agents-api/cmd/server/main.go b/services/agents-api/cmd/server/main.go
index a25dc4d36..87263e35a 100644
--- a/services/agents-api/cmd/server/main.go
+++ b/services/agents-api/cmd/server/main.go
@@ -123,7 +123,9 @@ func run() error {
 		managed = managedNodes.runtime
 	}
 	observationSources := map[string]runtimeobs.Source{}
-	if managed != nil {
+	if managedNodes != nil && managedNodes.setup != nil {
+		observationSources[managed.InstallationID] = managedNodes.setup
+	} else if managed != nil {
 		if source, ok := managed.Provider.(runtimeobs.Source); ok {
 			observationSources[managed.InstallationID] = source
 		}
@@ -178,7 +180,11 @@ func run() error {
 	var daemonHandler http.Handler
 	var registry *gateway.Registry
 	if wsURL := os.Getenv("AGENTS_API_DAEMON_WS_URL"); wsURL != "" {
-		daemonHandler, registry, err = runtime.NewGateway(executionStore, wsURL)
+		if managedNodes != nil && managedNodes.setup != nil {
+			daemonHandler, registry, err = runtime.NewGatewayWithURLResolver(executionStore, wsURL, managedNodes.setup.webSocketURL(wsURL))
+		} else {
+			daemonHandler, registry, err = runtime.NewGateway(executionStore, wsURL)
+		}
 		if err != nil {
 			return err
 		}
@@ -193,6 +199,9 @@ func run() error {
 		if err != nil {
 			return err
 		}
+		if managedNodes != nil && managedNodes.setup != nil {
+			options = append(options, api.WithSandboxDeploymentSetup(worker.InitializeSandboxDeployment))
+		}
 		workerDone = make(chan error, 1)
 		go func() { workerDone <- worker.Run(ctx) }()
 		defer func() {
@@ -233,7 +242,11 @@ func run() error {
 			<-samplerDone
 		}()
 	}
-	options = append(options, api.WithStartupConfiguration(coreStartupConfiguration(engine, kinds, registry != nil, modelProviderEndpoints, managedRuntimeProviderKind(managed), managed)))
+	startupManaged := managed
+	if managedNodes != nil && managedNodes.setup != nil {
+		startupManaged = managedNodes.setup.selected.Load()
+	}
+	options = append(options, api.WithStartupConfiguration(coreStartupConfiguration(engine, kinds, registry != nil, modelProviderEndpoints, managedRuntimeProviderKind(startupManaged), startupManaged)))
 	handler, err := api.NewHandler(executionStore, auth, engine, options...)
 	if err != nil {
 		return err
diff --git a/services/agents-api/cmd/server/managed_nodes.go b/services/agents-api/cmd/server/managed_nodes.go
index bf21221b9..c1c719323 100644
--- a/services/agents-api/cmd/server/managed_nodes.go
+++ b/services/agents-api/cmd/server/managed_nodes.go
@@ -15,9 +15,11 @@ import (
 	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox"
 	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox/node"
 	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+	"github.com/google/uuid"
 )
 
 type managedNodes struct {
+	setup         *managedSetup
 	runtime       *execution.RuntimeProvider
 	hub           *node.Hub
 	admin         *api.DeploymentAuthenticator
@@ -30,9 +32,22 @@ func configureManagedNodes(s *store.Store, owner func(context.Context) error) (*
 	if err != nil {
 		return nil, err
 	}
-	if built == nil {
+	setupID := os.Getenv("AGENTS_API_SANDBOX_INSTALLATION_ID")
+	if built == nil && setupID == "" {
 		return nil, nil
 	}
+	if built != nil && setupID != "" {
+		return nil, errors.New("Web sandbox setup cannot be combined with managed Runtime configuration")
+	}
+	if setupID != "" {
+		id, err := uuid.Parse(setupID)
+		if err != nil || id == uuid.Nil || id.String() != setupID {
+			return nil, errors.New("sandbox installation ID must be a canonical UUID")
+		}
+		if os.Getenv("AGENTS_API_DAEMON_WS_URL") == "" {
+			return nil, errors.New("Web sandbox setup requires daemon transport")
+		}
+	}
 	result := &managedNodes{closeProvider: closeProvider}
 	success := false
 	defer func() {
@@ -44,6 +59,9 @@ func configureManagedNodes(s *store.Store, owner func(context.Context) error) (*
 	if err != nil {
 		return nil, err
 	}
+	if setupID != "" && result.admin == nil {
+		return nil, errors.New("Web sandbox setup requires deployment administrator credentials")
+	}
 	result.hub = node.NewHub(node.HubOptions{
 		Authenticate: func(ctx context.Context, id, credential string) (node.Identity, error) {
 			n, err := s.AuthenticateRuntimeNode(ctx, id, credential)
@@ -74,6 +92,12 @@ func configureManagedNodes(s *store.Store, owner func(context.Context) error) (*
 			return s.HeartbeatRuntimeNode(ctx, n.NodeID, connection, epoch, store.RuntimeNodeHealth{ProviderReady: health.ProviderReady, Diagnostic: health.Diagnostic, CPUCount: health.CPUCount, AvailableMemoryBytes: health.AvailableMemoryBytes, AvailableDiskBytes: health.AvailableDiskBytes})
 		},
 	})
+	if setupID != "" {
+		result.setup = &managedSetup{store: s, hub: result.hub, installationID: setupID}
+		result.runtime = execution.NewDeferredRuntimeProvider(setupID, result.setup.load)
+		success = true
+		return result, nil
+	}
 	result.runtime = runtimeFromConfig(config, built)
 	result.runtime.Provider = result.hub.Provider(config.Provider, func(ctx context.Context, r sandbox.Reference) (string, error) {
 		return s.ResolveRuntimeNode(ctx, r.TenantID, r.EnvironmentID)
diff --git a/services/agents-api/cmd/server/managed_setup.go b/services/agents-api/cmd/server/managed_setup.go
new file mode 100644
index 000000000..a08ea601b
--- /dev/null
+++ b/services/agents-api/cmd/server/managed_setup.go
@@ -0,0 +1,96 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"sync/atomic"
+	"time"
+
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/execution"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/runtimeobs"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/sandbox/node"
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/store"
+)
+
+// managedSetup publishes one immutable selection to execution, bootstrap and
+// observation. The database owns the selection; this cache is never a writer.
+type managedSetup struct {
+	store          *store.Store
+	hub            *node.Hub
+	installationID string
+	selected       atomic.Pointer[execution.RuntimeProvider]
+}
+
+func (s *managedSetup) load(ctx context.Context) (*execution.RuntimeProvider, error) {
+	if selected := s.selected.Load(); selected != nil {
+		return selected, nil
+	}
+	setup, err := s.store.GetSandboxSetup(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if setup.InstallationID != s.installationID {
+		return nil, errors.New("sandbox installation does not match setup")
+	}
+	if setup.Provider == "" {
+		return nil, nil
+	}
+	provider := s.hub.Provider(setup.Provider, func(ctx context.Context, ref sandbox.Reference) (string, error) {
+		return s.store.ResolveRuntimeNode(ctx, ref.TenantID, ref.EnvironmentID)
+	})
+	selected := &execution.RuntimeProvider{InstallationID: setup.InstallationID, ProviderKind: setup.Provider,
+		CoreURL: setup.CoreURL + "/api/v1", BackendFingerprint: setup.BackendFingerprint, Provider: provider}
+	if setup.Provider == "microsandbox" {
+		selected.Suspension = &execution.RuntimeSuspensionPolicy{IdleTimeout: time.Duration(setup.IdleSeconds) * time.Second,
+			Retention: time.Duration(setup.RetentionSeconds) * time.Second, MaxActive: 4, MaxRetained: 16}
+	}
+	s.selected.CompareAndSwap(nil, selected)
+	return s.selected.Load(), nil
+}
+
+func (s *managedSetup) webSocketURL(fallback string) func(context.Context) (string, error) {
+	return func(ctx context.Context) (string, error) {
+		selected, err := s.load(ctx)
+		if err != nil {
+			return "", err
+		}
+		if selected == nil {
+			return fallback, nil
+		}
+		u, err := url.Parse(selected.CoreURL)
+		if err != nil {
+			return "", err
+		}
+		if u.Scheme == "https" {
+			u.Scheme = "wss"
+		} else {
+			u.Scheme = "ws"
+		}
+		u.Path = "/api/v1/agent-daemon/ws"
+		return u.String(), nil
+	}
+}
+
+func (s *managedSetup) ObservationProviderType() string {
+	if selected := s.selected.Load(); selected != nil {
+		return selected.ProviderKind
+	}
+	return ""
+}
+
+func (s *managedSetup) Observe(ctx context.Context, target runtimeobs.Target) (runtimeobs.Sample, error) {
+	selected, err := s.load(ctx)
+	if err != nil {
+		return runtimeobs.Sample{}, err
+	}
+	if selected == nil {
+		return runtimeobs.Sample{}, runtimeobs.ErrUnavailable
+	}
+	source, ok := selected.Provider.(runtimeobs.Source)
+	if !ok {
+		return runtimeobs.Sample{}, runtimeobs.ErrUnavailable
+	}
+	return source.Observe(ctx, target)
+}
diff --git a/services/agents-api/cmd/server/managed_setup_test.go b/services/agents-api/cmd/server/managed_setup_test.go
new file mode 100644
index 000000000..8d5000d23
--- /dev/null
+++ b/services/agents-api/cmd/server/managed_setup_test.go
@@ -0,0 +1,54 @@
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/MiniMax-AI-Dev/parsar/services/agents-api/internal/execution"
+	"github.com/google/uuid"
+)
+
+func TestWebSetupCreatesManagerWithoutLocalProvider(t *testing.T) {
+	t.Setenv("AGENTS_API_MANAGED_RUNTIMES_FILE", "")
+	t.Setenv("AGENTS_API_SANDBOX_INSTALLATION_ID", uuid.NewString())
+	t.Setenv("AGENTS_API_DAEMON_WS_URL", "ws://core:8091/api/v1/agent-daemon/ws")
+	digest := sha256.Sum256([]byte("synthetic-admin"))
+	path := filepath.Join(t.TempDir(), "digests.json")
+	if err := os.WriteFile(path, []byte(`["`+hex.EncodeToString(digest[:])+`"]`), 0600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE", path)
+	m, err := configureManagedNodes(nil, func(context.Context) error { return nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer m.close()
+	if m.setup == nil || m.admin == nil || m.hub == nil || m.runtime == nil || m.local != nil || m.runtime.Provider != nil {
+		t.Fatal("zero-node setup unexpectedly instantiated local compute or omitted management")
+	}
+	t.Setenv("AGENTS_API_SANDBOX_ADMIN_DIGESTS_FILE", "")
+	if _, err := configureManagedNodes(nil, nil); err == nil {
+		t.Fatal("setup accepted without admin authentication")
+	}
+}
+
+func TestSelectedSetupPublishesSameOriginForDaemonBootstrap(t *testing.T) {
+	for _, tc := range []struct{ origin, want string }{
+		{"https://core.example:8443/api/v1", "wss://core.example:8443/api/v1/agent-daemon/ws"},
+		{"http://127.0.0.1:8091/api/v1", "ws://127.0.0.1:8091/api/v1/agent-daemon/ws"},
+	} {
+		s := &managedSetup{}
+		s.selected.Store(&execution.RuntimeProvider{CoreURL: tc.origin, ProviderKind: "docker"})
+		got, err := s.webSocketURL("ws://private-core:8091/api/v1/agent-daemon/ws")(context.Background())
+		if err != nil || got != tc.want {
+			t.Fatalf("bootstrap URL=%s error=%v", got, err)
+		}
+		if s.ObservationProviderType() != "docker" {
+			t.Fatal("observation lost selected provider")
+		}
+	}
+}
diff --git a/services/agents-api/cmd/server/startup_configuration.go b/services/agents-api/cmd/server/startup_configuration.go
index a30d3c79d..c9cc93d26 100644
--- a/services/agents-api/cmd/server/startup_configuration.go
+++ b/services/agents-api/cmd/server/startup_configuration.go
@@ -16,7 +16,7 @@ func coreStartupConfiguration(defaultHarness string, enabledHarnesses []string,
 		modelProviders = append(modelProviders, v1.CoreHarnessModelProviderConfiguration{Harness: kind, EndpointConfigured: endpoints[kind]})
 	}
 	managedConfiguration := v1.CoreManagedSandboxConfiguration{}
-	if managed != nil {
+	if managed != nil && managedProviderKind != "" {
 		provider := managedProviderKind
 		managedConfiguration = v1.CoreManagedSandboxConfiguration{Enabled: true, Provider: &provider, Maintenance: managed.Maintenance}
 	}
diff --git a/services/agents-api/internal/runtime/gateway.go b/services/agents-api/internal/runtime/gateway.go
index e6de36d37..987e80cf4 100644
--- a/services/agents-api/internal/runtime/gateway.go
+++ b/services/agents-api/internal/runtime/gateway.go
@@ -2,6 +2,7 @@
 package runtime
 
 import (
+	"context"
 	"errors"
 	"net/http"
 	"net/url"
@@ -19,6 +20,12 @@ type DeviceStore interface {
 // NewGateway serves the V1 daemon executor transport for both managed and
 // user-managed Runtime. Its credentials never grant public Session API access.
 func NewGateway(s DeviceStore, publicWSURL string) (http.Handler, *gateway.Registry, error) {
+	return NewGatewayWithURLResolver(s, publicWSURL, nil)
+}
+
+// NewGatewayWithURLResolver allows a zero-node deployment to publish its chosen
+// public address after setup without replacing its gateway or live connections.
+func NewGatewayWithURLResolver(s DeviceStore, publicWSURL string, resolve func(context.Context) (string, error)) (http.Handler, *gateway.Registry, error) {
 	u, err := url.Parse(publicWSURL)
 	if err != nil || s == nil || (u.Scheme != "ws" && u.Scheme != "wss") || u.Hostname() == "" || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Path != "/api/v1/agent-daemon/ws" {
 		return nil, nil, errors.New("daemon URL must be an absolute ws(s) URL ending in /api/v1/agent-daemon/ws")
@@ -26,7 +33,7 @@ func NewGateway(s DeviceStore, publicWSURL string) (http.Handler, *gateway.Regis
 	registry := gateway.NewRegistry()
 	h := gateway.NewHandler(gateway.HandlerConfig{
 		Authenticator: gateway.NewAuthenticator(s), Registry: registry,
-		Heartbeat: s, PublicWSURL: publicWSURL,
+		Heartbeat: s, PublicWSURL: publicWSURL, ResolvePublicWSURL: resolve,
 	})
 	r := chi.NewRouter()
 	r.Route("/api/v1", func(r chi.Router) { gateway.RegisterRoutes(r, h) })
diff --git a/services/core-console/config.go b/services/core-console/config.go
index 6c4f59779..735bd308f 100644
--- a/services/core-console/config.go
+++ b/services/core-console/config.go
@@ -12,6 +12,7 @@ import (
 
 type config struct {
 	addr, origin, dist, token, password string
+	adminToken, nodePayloadDir          string
 	upstream                            *url.URL
 }
 
@@ -43,6 +44,19 @@ func loadConfig() (config, error) {
 	if c.password == c.token {
 		return config{}, errors.New("console password and Core bearer token must differ")
 	}
+	if file := os.Getenv("CORE_CONSOLE_SANDBOX_ADMIN_TOKEN_FILE"); file != "" {
+		c.adminToken, err = readSecret(file)
+		if err != nil {
+			return config{}, errors.New("CORE_CONSOLE_SANDBOX_ADMIN_TOKEN_FILE must name a private regular token file")
+		}
+		if c.adminToken == c.token || c.adminToken == c.password {
+			return config{}, errors.New("sandbox administrator credential must be separate")
+		}
+	}
+	c.nodePayloadDir = os.Getenv("CORE_CONSOLE_NODE_PAYLOAD_DIR")
+	if c.nodePayloadDir != "" && (!filepath.IsAbs(c.nodePayloadDir) || c.adminToken == "") {
+		return config{}, errors.New("node payload requires an absolute directory and paired administrator access")
+	}
 	return c, nil
 }
 
diff --git a/services/core-console/node_installation.go b/services/core-console/node_installation.go
new file mode 100644
index 000000000..bc5a5ea2b
--- /dev/null
+++ b/services/core-console/node_installation.go
@@ -0,0 +1,89 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+)
+
+// These are distribution artifacts, never installation configuration or secrets.
+// Serving the fixed list avoids a package registry or an arbitrary file endpoint.
+var nodePayloadFiles = map[string]bool{
+	"node_install.py": true, "manifest.json": true, "SHA256SUMS": true,
+	"native/bin/parsar-sandbox-node":              true,
+	"native/bin/agents-api-microsandbox-provider": true,
+	"native/microsandbox/msb":                     true,
+	"native/microsandbox/libkrunfw.so.5.6.1":      true,
+	"images/runtime.tar":                          true, "runtime/seccomp.json": true,
+}
+
+func nodeInstallerDigest(root *os.Root) (string, error) {
+	f, err := root.Open("node_install.py")
+	if err != nil {
+		return "", errors.New("node installer is missing")
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil || !info.Mode().IsRegular() || info.Size() > 1024*1024 {
+		return "", errors.New("invalid node installer")
+	}
+	digest := sha256.New()
+	if _, err = io.Copy(digest, f); err != nil {
+		return "", errors.New("cannot read node installer")
+	}
+	return hex.EncodeToString(digest.Sum(nil)), nil
+}
+
+func (h *console) serveNodePayload(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		w.Header().Set("Allow", "GET, HEAD")
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	name := strings.TrimPrefix(r.URL.Path, "/node-install/")
+	if !nodePayloadFiles[name] {
+		http.NotFound(w, r)
+		return
+	}
+	f, err := h.nodePayload.Open(name)
+	if err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil || !info.Mode().IsRegular() {
+		http.NotFound(w, r)
+		return
+	}
+	w.Header().Set("Content-Type", "application/octet-stream")
+	http.ServeContent(w, r, info.Name(), info.ModTime(), f)
+}
+
+func (h *console) serveConsoleConfiguration(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(struct {
+		SandboxAdmin        bool   `json:"sandbox_admin"`
+		NodeInstaller       bool   `json:"node_installer"`
+		NodeInstallerSHA256 string `json:"node_installer_sha256"`
+	}{h.adminToken != "", h.nodePayload != nil, h.nodeInstallerDigest})
+}
+
+// Node and Runtime credentials pass through unchanged to Core authentication.
+// Console or project credentials are never substituted on these public routes.
+func nodeTransportRequest(r *http.Request) bool {
+	switch r.URL.Path {
+	case "/core/v1/sandbox/enroll", "/api/v1/agent-daemon/bootstrap":
+		return r.Method == http.MethodPost && r.Header.Get("Upgrade") == ""
+	case "/core/v1/sandbox/node/identity", "/api/v1/agent-daemon/device-status":
+		return r.Method == http.MethodGet && r.Header.Get("Upgrade") == ""
+	case "/core/v1/sandbox/node/connect", "/api/v1/agent-daemon/ws":
+		return r.Method == http.MethodGet && strings.EqualFold(r.Header.Get("Upgrade"), "websocket")
+	}
+	return false
+}
diff --git a/services/core-console/node_installation_test.go b/services/core-console/node_installation_test.go
new file mode 100644
index 000000000..21bc98fca
--- /dev/null
+++ b/services/core-console/node_installation_test.go
@@ -0,0 +1,141 @@
+package main
+
+import (
+	"github.com/gorilla/websocket"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+func TestPairedConsoleKeepsAdminAndNodeCredentialsSeparated(t *testing.T) {
+	var calls atomic.Int32
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		calls.Add(1)
+		want := "Bearer server-admin"
+		if strings.HasPrefix(r.URL.Path, "/v1/") {
+			want = "Bearer project-token"
+		}
+		if nodeTransportRequest(r) {
+			want = "Bearer node-token"
+		}
+		if r.Header.Get("Authorization") != want {
+			t.Errorf("incorrect upstream authority for %s", r.URL.Path)
+		}
+		_, _ = io.WriteString(w, "{}")
+	}))
+	defer upstream.Close()
+	u, _ := url.Parse(upstream.URL)
+	dist, payload := t.TempDir(), t.TempDir()
+	for _, file := range []struct{ path, value string }{{filepath.Join(dist, "index.html"), "console"}, {filepath.Join(payload, "node_install.py"), "print('installer')"}, {filepath.Join(payload, "caller.key"), "must-not-be-served"}} {
+		if err := os.WriteFile(file.path, []byte(file.value), 0600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	h, err := newConsole(config{origin: testOrigin, upstream: u, dist: dist, token: "project-token", password: "private-console-password", adminToken: "server-admin", nodePayloadDir: payload})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer h.Close()
+	server := httptest.NewServer(h)
+	defer server.Close()
+	for _, tc := range []struct {
+		method, path, auth string
+		status             int
+	}{
+		{"POST", "/core/v1/sandbox/deployment", "basic", 200},
+		{"POST", "/core/v1/sandbox/deployment", "none", 401},
+		{"GET", "/core/v1/sandbox/nodes", "node", 401},
+		{"GET", "/v1/agents", "basic", 200},
+		{"POST", "/core/v1/sandbox/enroll", "node", 200},
+		{"POST", "/core/v1/sandbox/enroll", "basic", 403},
+		{"POST", "/api/v1/agent-daemon/bootstrap", "node", 200},
+		{"POST", "/api/v1/agent-daemon/unknown", "node", 403},
+		{"GET", "/console/config", "basic", 200},
+		{"GET", "/console/config", "none", 401},
+		{"GET", "/node-install/node_install.py", "none", 200},
+		{"GET", "/node-install/caller.key", "none", 404},
+		{"POST", "/node-install/node_install.py", "none", 405},
+	} {
+		r := consoleRequest(t, server, tc.method, tc.path)
+		if tc.auth == "none" {
+			r.Header.Del("Authorization")
+		}
+		if tc.auth == "node" {
+			r.Header.Set("Authorization", "Bearer node-token")
+			r.Header.Del("Origin")
+			r.Header.Del("Sec-Fetch-Site")
+		}
+		response, body := responseBody(t, server, r)
+		if response.StatusCode != tc.status {
+			t.Errorf("%s %s/%s status=%d", tc.method, tc.path, tc.auth, response.StatusCode)
+		}
+		if strings.Contains(body, "server-admin") || strings.Contains(body, "project-token") || strings.Contains(body, "must-not-be-served") {
+			t.Fatal("credential leaked")
+		}
+		if tc.path == "/console/config" && tc.status == 200 && !strings.Contains(body, `"sandbox_admin":true`) {
+			t.Fatal("paired mode missing")
+		}
+	}
+	if calls.Load() != 4 {
+		t.Fatalf("unexpected upstream requests: %d", calls.Load())
+	}
+	r := consoleRequest(t, server, "POST", "/core/v1/sandbox/deployment")
+	r.Header.Set("Origin", "https://foreign.invalid")
+	response, _ := responseBody(t, server, r)
+	if response.StatusCode != 403 {
+		t.Fatal("cross-origin setup reached Core")
+	}
+}
+
+func TestPairedConsoleProxiesAuthenticatedNodeWebSockets(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer node-token" {
+			t.Error("node authority replaced")
+			http.Error(w, "unauthorized", 401)
+			return
+		}
+		upgrader := websocket.Upgrader{}
+		ws, err := upgrader.Upgrade(w, r, nil)
+		if err != nil {
+			t.Error(err)
+			return
+		}
+		defer ws.Close()
+		if err := ws.WriteMessage(websocket.TextMessage, []byte("node-connected")); err != nil {
+			t.Error(err)
+		}
+	}))
+	defer upstream.Close()
+	u, _ := url.Parse(upstream.URL)
+	dist := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dist, "index.html"), []byte("console"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	h, err := newConsole(config{origin: testOrigin, upstream: u, dist: dist, token: "project-token", password: "console-password", adminToken: "server-admin"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer h.Close()
+	server := httptest.NewServer(h)
+	defer server.Close()
+	for _, path := range []string{"/core/v1/sandbox/node/connect", "/api/v1/agent-daemon/ws"} {
+		ws, response, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(server.URL, "http")+path, http.Header{"Host": {"127.0.0.1:8080"}, "Authorization": {"Bearer node-token"}})
+		if err != nil {
+			if response != nil {
+				t.Fatalf("proxy handshake %d: %v", response.StatusCode, err)
+			}
+			t.Fatal(err)
+		}
+		_, data, err := ws.ReadMessage()
+		ws.Close()
+		if err != nil || string(data) != "node-connected" {
+			t.Fatalf("proxy message=%q error=%v", data, err)
+		}
+	}
+}
diff --git a/services/core-console/sandbox_admin.go b/services/core-console/sandbox_admin.go
index 21866b555..4bed50695 100644
--- a/services/core-console/sandbox_admin.go
+++ b/services/core-console/sandbox_admin.go
@@ -15,7 +15,9 @@ func sandboxAdminRequest(r *http.Request) bool {
 	parts := strings.Split(strings.TrimPrefix(r.URL.Path, base), "/")
 	if len(parts) == 1 {
 		switch parts[0] {
-		case "deployment", "nodes":
+		case "deployment":
+			return r.Method == http.MethodGet || r.Method == http.MethodPost
+		case "nodes":
 			return r.Method == http.MethodGet
 		case "enrollment-tokens":
 			return r.Method == http.MethodPost
diff --git a/services/core-console/server.go b/services/core-console/server.go
index 485bc69cb..511899b77 100644
--- a/services/core-console/server.go
+++ b/services/core-console/server.go
@@ -16,11 +16,13 @@ import (
 
 type console struct {
 	config
-	root      *os.Root
-	proxy     *httputil.ReverseProxy
-	transport *http.Transport
-	host      string
-	password  [sha256.Size]byte
+	root                *os.Root
+	nodePayload         *os.Root
+	nodeInstallerDigest string
+	proxy               *httputil.ReverseProxy
+	transport           *http.Transport
+	host                string
+	password            [sha256.Size]byte
 }
 
 func newConsole(c config) (*console, error) {
@@ -35,6 +37,19 @@ func newConsole(c config) (*console, error) {
 	}
 	origin, _ := url.Parse(c.origin)
 	h := &console{config: c, root: root, host: origin.Host, password: sha256.Sum256([]byte(c.password))}
+	if c.nodePayloadDir != "" {
+		h.nodePayload, err = os.OpenRoot(c.nodePayloadDir)
+		if err != nil {
+			root.Close()
+			return nil, errors.New("cannot open node installation payload")
+		}
+		h.nodeInstallerDigest, err = nodeInstallerDigest(h.nodePayload)
+		if err != nil {
+			h.nodePayload.Close()
+			root.Close()
+			return nil, err
+		}
+	}
 	h.transport = http.DefaultTransport.(*http.Transport).Clone()
 	// Credentials go only to the configured Core, never an ambient HTTP proxy.
 	h.transport.Proxy = nil
@@ -49,8 +64,10 @@ func newConsole(c config) (*console, error) {
 			r.Out.Header.Del("Cookie")
 			r.Out.Header.Del("Origin")
 			r.Out.Header.Del("Referer")
-			if sandboxAdminRequest(r.In) {
+			if nodeTransportRequest(r.In) || (sandboxAdminRequest(r.In) && c.adminToken == "") {
 				r.Out.Header.Set("Authorization", r.In.Header.Get("Authorization"))
+			} else if sandboxAdminRequest(r.In) {
+				r.Out.Header.Set("Authorization", "Bearer "+c.adminToken)
 			} else {
 				r.Out.Header.Set("Authorization", "Bearer "+c.token)
 			}
@@ -81,6 +98,9 @@ func newConsole(c config) (*console, error) {
 func (h *console) Close() {
 	h.transport.CloseIdleConnections()
 	_ = h.root.Close()
+	if h.nodePayload != nil {
+		_ = h.nodePayload.Close()
+	}
 }
 
 func (h *console) ServeHTTP(w http.ResponseWriter, r *http.Request) {
@@ -93,6 +113,22 @@ func (h *console) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		_, _ = io.WriteString(w, "ok\n")
 		return
 	}
+	if h.adminToken != "" && nodeTransportRequest(r) {
+		if r.Host != h.host || !safePath(r.URL.Path) || r.URL.IsAbs() || !explicitBearer(r) || (r.Header.Get("Origin") != "" && r.Header.Get("Origin") != h.origin) {
+			http.Error(w, "Invalid node transport request", http.StatusForbidden)
+			return
+		}
+		h.proxy.ServeHTTP(w, r)
+		return
+	}
+	if h.nodePayload != nil && strings.HasPrefix(r.URL.Path, "/node-install/") {
+		if r.Host != h.host || !safePath(r.URL.Path) || r.URL.IsAbs() {
+			http.NotFound(w, r)
+			return
+		}
+		h.serveNodePayload(w, r)
+		return
+	}
 	if !h.sameOrigin(r) {
 		http.Error(w, "Forbidden", http.StatusForbidden)
 		return
@@ -101,7 +137,7 @@ func (h *console) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Invalid request", http.StatusBadRequest)
 		return
 	}
-	if r.URL.Path == "/core" || strings.HasPrefix(r.URL.Path, "/core/") {
+	if (r.URL.Path == "/core" || strings.HasPrefix(r.URL.Path, "/core/")) && h.adminToken == "" {
 		if !sandboxAdminRequest(r) {
 			http.NotFound(w, r)
 			return
@@ -122,6 +158,18 @@ func (h *console) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Authentication required", http.StatusUnauthorized)
 		return
 	}
+	if r.URL.Path == "/console/config" && r.Method == http.MethodGet {
+		h.serveConsoleConfiguration(w, r)
+		return
+	}
+	if r.URL.Path == "/core" || strings.HasPrefix(r.URL.Path, "/core/") {
+		if !sandboxAdminRequest(r) {
+			http.NotFound(w, r)
+			return
+		}
+		h.proxy.ServeHTTP(w, r)
+		return
+	}
 	if r.URL.Path == "/v1" || strings.HasPrefix(r.URL.Path, "/v1/") {
 		h.proxy.ServeHTTP(w, r)
 		return

From a8a2828e77b27225ceff1f939263dc27369cf410 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 21:01:43 +0800
Subject: [PATCH 7/9] fix(install): preserve node setup across interrupted
 installation retries

---
 deploy/install/install.py           | 11 +++++++++--
 deploy/install/node_install.py      |  4 +++-
 deploy/install/test_install.py      | 14 ++++++++++++++
 deploy/install/test_node_install.py | 12 ++++++++++++
 4 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/deploy/install/install.py b/deploy/install/install.py
index 6ba42e676..e3ad45db2 100644
--- a/deploy/install/install.py
+++ b/deploy/install/install.py
@@ -13,6 +13,7 @@
 import stat
 import subprocess
 import sys
+import tempfile
 import time
 import urllib.error
 import urllib.request
@@ -269,8 +270,14 @@ def prepare_node_payload(root, state, bundle):
             if target.is_symlink() or not target.is_file() or digest(target) != digest(source):
                 raise InstallError("Installed node payload differs; preserve it and inspect the distribution")
         else:
-            shutil.copyfile(source, target)
-            target.chmod(0o600)
+            descriptor, temporary = tempfile.mkstemp(prefix=".payload-", dir=target.parent)
+            os.close(descriptor)
+            try:
+                shutil.copyfile(source, temporary)
+                os.replace(temporary, target)
+            finally:
+                if os.path.exists(temporary):
+                    os.unlink(temporary)
 
 
 def import_runtime(root, state, manifest, bundle):
diff --git a/deploy/install/node_install.py b/deploy/install/node_install.py
index 4870ca568..6d17bfb05 100644
--- a/deploy/install/node_install.py
+++ b/deploy/install/node_install.py
@@ -252,7 +252,9 @@ def install(args, token):
         for name in names:
             download(args.source_url, name, root, sums[name])
         safe_directory(root / "state/node")
-        write_once(root / "provider.json", json_text(provider_config(root, args, manifest)))
+        # Retain the original network policy when recovering a partial installation.
+        if not existing_file(root / "provider.json"):
+            write_once(root / "provider.json", json_text(provider_config(root, args, manifest)))
         unit = root / ("parsar-node-" + args.installation_id + ".service")
         write_once(unit, service_unit(root))
         marker = root / "registered.json"
diff --git a/deploy/install/test_install.py b/deploy/install/test_install.py
index 96b124c62..e195aceb2 100644
--- a/deploy/install/test_install.py
+++ b/deploy/install/test_install.py
@@ -118,6 +118,20 @@ def test_node_payload_exports_only_matched_distribution_files(self):
         with self.assertRaises(install.InstallError):
             install.prepare_node_payload(self.root, state, bundle)
 
+    def test_interrupted_payload_copy_can_be_retried(self):
+        state = self.initialize()
+        bundle = self.bundle()
+        def interrupted(source, target):
+            Path(target).write_bytes(b"partial")
+            raise OSError("copy interrupted")
+        with mock.patch.object(install.shutil, "copyfile", side_effect=interrupted):
+            with self.assertRaises(OSError):
+                install.prepare_node_payload(self.root, state, bundle)
+        self.assertFalse((self.root / "node-payload/node_install.py").exists())
+        install.prepare_node_payload(self.root, state, bundle)
+        self.assertEqual((self.root / "node-payload/node_install.py").read_bytes(),
+                         (bundle / "node_install.py").read_bytes())
+
     def test_repeat_installation_preserves_execution_identity_and_all_secrets(self):
         first = self.initialize()
         keys = self.document("config/keys.json")
diff --git a/deploy/install/test_node_install.py b/deploy/install/test_node_install.py
index de656b7f6..9ec759c74 100644
--- a/deploy/install/test_node_install.py
+++ b/deploy/install/test_node_install.py
@@ -111,6 +111,18 @@ def test_unconfirmed_registration_retains_state_removes_token_and_does_not_start
         self.assertEqual(list(self.root.glob(".enrollment-*")), [])
         self.assertFalse(any("enable" in call for call, _ in self.calls))
 
+    def test_microsandbox_registration_retry_retains_original_dns_policy(self):
+        self.args.provider = "microsandbox"
+        self.fail_registration = True
+        with self.assertRaises(installer.InstallError):
+            self.install()
+        original = (self.root / "provider.json").read_bytes()
+        self.fail_registration = False
+        with mock.patch.object(installer.socket, "getaddrinfo", side_effect=OSError("DNS unavailable")):
+            self.install()
+        self.assertEqual((self.root / "provider.json").read_bytes(), original)
+        self.assertTrue((self.root / "registered.json").exists())
+
     def test_different_commit_provider_or_core_cannot_overwrite_retained_installation(self):
         self.install()
         original = (self.root / "provider.json").read_bytes()

From 649d2f2e275057e4af5426e355daec1c46009298 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 21:03:38 +0800
Subject: [PATCH 8/9] docs: clarify node prerequisite check order

---
 docs/getting-started/install.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 777c9743c..afb7122b3 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -120,7 +120,8 @@ external Core still requires its separate administrator key.
 
 The target host needs Python 3.9+, a systemd user session with lingering enabled,
 and either Docker socket access or microsandbox's KVM/native-library prerequisites.
-The command reports unmet prerequisites before downloading the Runtime.
+The command checks host access before downloading the Runtime and verifies
+microsandbox's shared libraries after downloading its native programs.
 The console serves only fixed, non-secret distribution files at `/node-install/`;
 private installation configuration is never part of this payload. Retain the
 installed `node-payload/` directory.

From 3a947c5a8e2d47aacf92990e12ed7c5d8b61b207 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Wed, 23 Sep 2026 21:48:26 +0800
Subject: [PATCH 9/9] test(web): synchronize Dashboard pagination checks with
 Session metrics

---
 apps/web/e2e/agents-lifecycle.spec.ts | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/apps/web/e2e/agents-lifecycle.spec.ts b/apps/web/e2e/agents-lifecycle.spec.ts
index 599ef5bf2..49c89ce2c 100644
--- a/apps/web/e2e/agents-lifecycle.spec.ts
+++ b/apps/web/e2e/agents-lifecycle.spec.ts
@@ -3030,17 +3030,26 @@ test("publishes Dashboard counts only after every top-level Agent and Session pa
     });
   });
 
-  await openSessionsFromHome(page);
-  await page.getByRole("button", { name: "Dashboard", exact: true }).click();
+  await page.goto("/");
   const dashboard = page.locator(".dashboard-page");
+  // The synthetic second Session has no Runtime observation. Let that initial
+  // snapshot finish before navigation, so requests cannot be aborted mid-chain.
+  await expect(dashboard.locator(".dashboard-source-badge").filter({ hasText: "Runtime" })).toContainText("Unavailable");
+  expect(sessionAfters).toEqual([null, "session_snapshot", null, "session_snapshot"]);
+  await page.getByRole("button", { name: "Sessions", exact: true }).click();
+  await expect.poll(() => sessionAfters.length).toBe(6);
+  await page.getByRole("button", { name: "Dashboard", exact: true }).click();
   await expect(dashboard.locator(".dashboard-summary > div").filter({ hasText: "Agents" })).toContainText("3");
   await expect(dashboard.locator(".dashboard-summary > div").filter({ hasText: "Sessions" })).toContainText("2");
   expect(agentAfters).toEqual([null, "agent_b"]);
-  // Session collection loads once for the page and once per Runtime snapshot.
-  // Returning to Dashboard refreshes Runtime immediately instead of waiting 30 seconds.
-  await expect.poll(() => sessionAfters.length).toBe(6);
-  expect(sessionAfters.filter((after) => after === null)).toHaveLength(3);
-  expect(sessionAfters.filter((after) => after === "session_snapshot")).toHaveLength(3);
+  // Session collection loads once; the unavailable Runtime snapshot is retried
+  // on entry to Sessions and again on return to Dashboard. Each reads both pages.
+  await expect.poll(() => sessionAfters).toEqual([
+    null, "session_snapshot",
+    null, "session_snapshot",
+    null, "session_snapshot",
+    null, "session_snapshot",
+  ]);
 });
 
 test("keeps the previous Dashboard result when pagination exceeds the safety limit", async ({ page, request }) => {