feat: make command parameter optional for POST /api/sandboxes

app/api/sandboxes/route.ts

@@ -20,21 +20,22 @@ export async function OPTIONS() {
 /**
  * POST /api/sandboxes
  *
- * Creates a new ephemeral sandbox environment and executes a command.
+ * Creates a new ephemeral sandbox environment. Optionally executes a command.
  * Sandboxes are isolated Linux microVMs that can be used to evaluate
  * account-generated code, run AI agent output safely, or execute reproducible tasks.
  * The sandbox will automatically stop after the timeout period.
  *
  * Authentication: x-api-key header or Authorization Bearer token required.
  *
  * Request body:
- * - command: string (required) - The command to execute in the sandbox
+ * - command: string (optional) - The command to execute in the sandbox. If omitted, sandbox is created without running any command.
  * - args: string[] (optional) - Arguments to pass to the command
  * - cwd: string (optional) - Working directory for command execution
  *
  * Response (200):
  * - status: "success"
- * - sandboxes: [{ sandboxId, sandboxStatus, timeout, createdAt, runId }]
+ * - sandboxes: [{ sandboxId, sandboxStatus, timeout, createdAt, runId? }]
+ *   - runId is only included when a command was provided
  *
  * Error (400/401):
  * - status: "error"

lib/sandbox/createSandboxPostHandler.ts

@@ -10,13 +10,14 @@ import { selectAccountSnapshots } from "@/lib/supabase/account_snapshots/selectA
 /**
  * Handler for POST /api/sandboxes.
  *
- * Creates a Vercel Sandbox (from account's snapshot if available, otherwise fresh)
- * and triggers the run-sandbox-command task to execute the command.
+ * Creates a Vercel Sandbox (from account's snapshot if available, otherwise fresh).
+ * If a command is provided, triggers the run-sandbox-command task to execute it.
+ * If no command is provided, simply creates the sandbox without running any command.
  * Requires authentication via x-api-key header or Authorization Bearer token.
  * Saves sandbox info to the account_sandboxes table.
  *
  * @param request - The request object
- * @returns A NextResponse with sandbox creation result including runId
+ * @returns A NextResponse with sandbox creation result (includes runId only if command was provided)
  */
 export async function createSandboxPostHandler(request: NextRequest): Promise<NextResponse> {
   const validated = await validateSandboxBody(request);
@@ -39,19 +40,21 @@ export async function createSandboxPostHandler(request: NextRequest): Promise<Ne
       sandbox_id: result.sandboxId,
     });
 
-    // Trigger the command execution task
+    // Trigger the command execution task only if a command was provided
     let runId: string | undefined;
-    try {
-      const handle = await triggerRunSandboxCommand({
-        command: validated.command,
-        args: validated.args,
-        cwd: validated.cwd,
-        sandboxId: result.sandboxId,
-        accountId: validated.accountId,
-      });
-      runId = handle.id;
-    } catch (triggerError) {
-      console.error("Failed to trigger run-sandbox-command task:", triggerError);
+    if (validated.command) {
+      try {
+        const handle = await triggerRunSandboxCommand({
+          command: validated.command,
+          args: validated.args,
+          cwd: validated.cwd,
+          sandboxId: result.sandboxId,
+          accountId: validated.accountId,
+        });
+        runId = handle.id;
+      } catch (triggerError) {
+        console.error("Failed to trigger run-sandbox-command task:", triggerError);
+      }
     }
 
     return NextResponse.json(

lib/sandbox/validateSandboxBody.ts

@@ -6,7 +6,7 @@ import { safeParseJson } from "@/lib/networking/safeParseJson";
 import { z } from "zod";
 
 export const sandboxBodySchema = z.object({
-  command: z.string({ message: "command is required" }).min(1, "command cannot be empty"),
+  command: z.string().min(1, "command cannot be empty").optional(),
   args: z.array(z.string()).optional(),
   cwd: z.string().optional(),
 });