fix: guard server startup to avoid port conflicts

Add health check before starting sandbox-agent to prevent 'address already
in use' errors on subsequent requests. The isServerRunning() function probes
the health endpoint to determine if setup should be skipped.

Co-authored-by: Shelley <shelley@exe.dev>

docs/deploy/cloudflare.mdx

@@ -25,7 +25,7 @@ cd my-sandbox
 ## TypeScript Example
 
 ```typescript
-import { getSandbox, proxyToSandbox } from "@cloudflare/sandbox";
+import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";
 export { Sandbox } from "@cloudflare/sandbox";
 
 type Env = {
@@ -34,6 +34,16 @@ type Env = {
   OPENAI_API_KEY?: string;
 };
 
+/** Check if sandbox-agent is already running by probing its health endpoint */
+async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
+  try {
+    const result = await sandbox.exec("curl -sf http://localhost:8000/v1/health");
+    return result.success;
+  } catch {
+    return false;
+  }
+}
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     // Proxy requests to exposed ports first
@@ -43,6 +53,10 @@ export default {
     const { hostname } = new URL(request.url);
     const sandbox = getSandbox(env.Sandbox, "sandbox-agent");
 
+    // Check if server is already running to avoid port conflicts
+    const alreadyRunning = await isServerRunning(sandbox);
+
+    if (!alreadyRunning) {
       // Install sandbox-agent
       await sandbox.exec(
         "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
@@ -65,13 +79,16 @@ export default {
 
       // Wait for server to start
       await new Promise((r) => setTimeout(r, 2000));
+    }
 
     // Expose the port with a preview URL
     const exposed = await sandbox.exposePort(8000, { hostname });
 
     return Response.json({
       endpoint: exposed.url,
-      message: "sandbox-agent server is running",
+      message: alreadyRunning
+        ? "sandbox-agent server was already running"
+        : "sandbox-agent server started",
     });
   },
 };

examples/cloudflare/src/cloudflare.ts

@@ -7,6 +7,16 @@ type Env = {
   OPENAI_API_KEY?: string;
 };
 
+/** Check if sandbox-agent is already running by probing its health endpoint */
+async function isServerRunning(sandbox: Sandbox): Promise<boolean> {
+  try {
+    const result = await sandbox.exec("curl -sf http://localhost:8000/v1/health");
+    return result.success;
+  } catch {
+    return false;
+  }
+}
+
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
     // Proxy requests to exposed ports first
@@ -16,6 +26,10 @@ export default {
     const { hostname } = new URL(request.url);
     const sandbox = getSandbox(env.Sandbox, "sandbox-agent");
 
+    // Check if server is already running to avoid port conflicts
+    const alreadyRunning = await isServerRunning(sandbox);
+
+    if (!alreadyRunning) {
       console.log("Installing sandbox-agent...");
       await sandbox.exec(
         "curl -fsSL https://releases.rivet.dev/sandbox-agent/latest/install.sh | sh"
@@ -38,6 +52,7 @@ export default {
 
       // Wait for server to start
       await new Promise((r) => setTimeout(r, 2000));
+    }
 
     // Expose the port with a preview URL
     const exposed = await sandbox.exposePort(8000, { hostname });
@@ -46,7 +61,9 @@ export default {
 
     return Response.json({
       endpoint: exposed.url,
-      message: "sandbox-agent server is running",
+      message: alreadyRunning
+        ? "sandbox-agent server was already running"
+        : "sandbox-agent server started",
     });
   },
 };