Network & Preview

SeaCloud Sandbox exposes services through port-based preview URLs. Runtime API traffic usually uses port 9000; your application should listen on its own port, such as 3000.

URL Model

https://{port}-{sandboxID}.{envdBaseDomain}/

URL	Meaning
`envdUrl`, usually `https://9000-{sandboxID}...`	Runtime API, health, files, and processes.
`https://3000-{sandboxID}...`	App listening on port `3000`.

await sandbox.files.makeDir("/root/workspace/site");
await sandbox.files.write(
  "/root/workspace/site/index.html",
  "<!doctype html><h1>Hello SeaCloud</h1>",
);

await sandbox.commands.run("python3", {
  args: ["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace/site"],
  background: true,
});

console.log(sandbox.getHost(3000));

sandbox.files.make_dir("/root/workspace/site")
sandbox.files.write(
    "/root/workspace/site/index.html",
    "<!doctype html><h1>Hello SeaCloud</h1>",
)
sandbox.commands.run(
    "python3",
    args=["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace/site"],
    background=True,
)
print(sandbox.get_host(3000))

Vite-Style Server

await sandbox.commands.run("sh", {
  cwd: "/root/workspace",
  args: ["-lc", "npm run dev -- --host 0.0.0.0 --port 3000"],
  background: true,
});

console.log(sandbox.getHost(3000));

Curl Derivation

If you are using raw APIs and already have envdUrl, derive the app URL by replacing the runtime port with the app port.

APP_URL=$(printf '%s' "${ENVD_URL}" | sed 's#://9000-#://3000-#')
echo "${APP_URL}"

Runtime Health And Proxy

Use runtime health to distinguish runtime reachability from app readiness:

curl -i "${ENVD_URL}/health"

Expected managed-runtime health is usually 204 No Content. GET {envdUrl}/ may return a small JSON response such as { "status": "ok" }; that does not mean your app is served on port 9000.

Runtime also supports an internal proxy form:

GET {envdUrl}/proxy/3000/

The external wildcard URL is still the preferred app preview URL:

https://3000-{sandboxID}.{envdBaseDomain}/

Troubleshooting

Symptom	Check
`9000` returns health but the app is missing	`9000` is the runtime API port, not your app port.
App URL returns `502`	Process exited, wrong port, or service only binds to `127.0.0.1`.
Blank page	HTML is served but assets are missing or using a wrong base path.
WebSocket fails	Confirm the framework uses the same host and public port route.
`readyCmd` passes but preview fails	Confirm `readyCmd` checks the same port that users open.