Ref Vercel Sandbox

SDK API

Sandbox.create(options?)

const sandbox = await Sandbox.create({
  // All optional
  timeout: 300000,      // 5 min default, max 45 min (Hobby)
});

sandbox.writeFiles(files)

// v1.9.0: takes an array of {path, content: Buffer, mode?} objects
await sandbox.writeFiles([
  { path: "index.js", content: Buffer.from("console.log('hello');") },
  { path: "package.json", content: Buffer.from(JSON.stringify({ dependencies: { express: "^4.18.0" } })) },
  // Optional: set file permissions (e.g., executable)
  { path: "run.sh", content: Buffer.from("node index.js"), mode: 0o755 },
]);

sandbox.runCommand(command)

// Returns CommandFinished directly — exitCode is already populated, no .wait() needed
const cmd = await sandbox.runCommand("npm install && node index.js");
const stdout = await cmd.output("stdout"); // "stdout" | "stderr" | "both"
const stderr = await cmd.output("stderr");
console.log(cmd.exitCode);    // 0 = success

sandbox.readFile(path)

const content = await sandbox.readFile("output.json");

sandbox.domain()

const url = await sandbox.domain(); // get public URL for HTTP server

sandbox.stop()

await sandbox.stop();

For CodeGym: Code Execution Pattern

import { Sandbox } from "@vercel/sandbox";

async function executeUserCode(
  userCode: string,
  testHarness: string,
  language: "javascript" | "typescript" | "python"
) {
  const sandbox = await Sandbox.create();

  try {
    if (language === "javascript" || language === "typescript") {
      // writeFiles takes an array of {path, content: Buffer} objects
      await sandbox.writeFiles([
        { path: "solution.js", content: Buffer.from(userCode) },
        { path: "test.js", content: Buffer.from(testHarness) },
      ]);
      // runCommand returns CommandFinished directly — exitCode already populated
      const cmd = await sandbox.runCommand("node test.js");
      return {
        stdout: await cmd.output("stdout"),
        stderr: await cmd.output("stderr"),
        exitCode: cmd.exitCode,
        passed: cmd.exitCode === 0,
      };
    }

    if (language === "python") {
      await sandbox.writeFiles([
        { path: "solution.py", content: Buffer.from(userCode) },
        { path: "test_solution.py", content: Buffer.from(testHarness) },
      ]);
      const cmd = await sandbox.runCommand("python3 test_solution.py");
      return {
        stdout: await cmd.output("stdout"),
        stderr: await cmd.output("stderr"),
        exitCode: cmd.exitCode,
        passed: cmd.exitCode === 0,
      };
    }
  } finally {
    await sandbox.stop();
  }
}

System Specs

• Runtimes: node24, node22, python3.13
• Sudo: Available as vercel-sandbox user
• Filesystem: Ephemeral — lost when sandbox stops
• Network: Available by default (can restrict with NetworkPolicy)
• Default timeout: 5 minutes
• Max timeout: 45 min (Hobby), 5 hours (Pro/Enterprise)
• Snapshots: Can snapshot a sandbox state and restore later

Gotchas

• VERCEL_TOKEN required — get from Vercel dashboard Settings > Tokens
• Cold start — first sandbox creation takes a few seconds
• Ephemeral filesystem — all files deleted when sandbox stops
• npm packages — need to npm install inside the sandbox if you need deps
• cmd.wait() — must await to get exitCode, otherwise it returns immediately
• Pricing — check Vercel Sandbox pricing; Hobby plan has limits
• Use for stretch goal — if Sandbox setup is blocked, fall back to in-browser execution with Function constructor or eval (for JS only)

Fallback: In-Browser Execution (No Sandbox)

For JS/TS only, if Sandbox is unavailable:

// Client-side execution using Function constructor
function executeInBrowser(userCode: string, testCode: string) {
  try {
    const fn = new Function(userCode + "\n" + testCode);
    const result = fn();
    return { passed: true, output: result };
  } catch (error) {
    return { passed: false, error: error.message };
  }
}

This is less secure but works for a hackathon demo with JS problems only.