tpmjs/docs/vercel-sandbox-api-question.md

Vercel Sandbox SDK API Research Request

Context

We're building a TPMJS executor template that runs npm packages in isolated Vercel Sandbox VMs. The executor needs to:

1. Create a sandbox VM
2. Install an npm package (npm install @tpmjs/hello@latest)
3. Write a Node.js script file to the sandbox
4. Execute the script and capture stdout/stderr
5. Parse the output and return results
6. Clean up the sandbox

Current Problem

Our code assumes the @vercel/sandbox SDK has this API:

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

const sandbox = await Sandbox.create({
  runtime: 'node22',
  timeout: 2 * 60 * 1000,
});

// We assumed this signature:
await sandbox.runCommand({
  cmd: 'npm',
  args: ['install', '--no-save', packageSpec],
  cwd: '/vercel/sandbox',
  stdout: someWritableStream,
  stderr: someWritableStream,
});

await sandbox.writeFiles([
  { path: '/vercel/sandbox/execute.cjs', content: Buffer.from(script) },
]);

await sandbox.stop();

But TypeScript is telling us the actual signature is:

Overload 1 of 3: (command: string, args?: string[], opts?: { signal?: AbortSignal }) => Promise<CommandFinished>

Questions to Research

1. What is the exact @vercel/sandbox SDK API?

We need the current, accurate API for version ^1.1.5 of @vercel/sandbox:

• Sandbox.create() - What options does it accept?
• How do you run commands? What's the method signature?
• How do you capture stdout/stderr from commands?
• How do you write files to the sandbox?
• How do you read files from the sandbox?
• How do you stop/destroy the sandbox?

2. What is the correct way to run commands and capture output?

Our use case:

// Install npm package
await sandbox.???('npm install @tpmjs/hello@latest');

// Run a script and capture output
const result = await sandbox.???('node execute.cjs');
console.log(result.stdout); // Need this
console.log(result.stderr); // Need this

3. What is the correct way to write files?

We need to write a JavaScript file to the sandbox filesystem:

const script = `
  const pkg = require('@tpmjs/hello');
  const result = await pkg.helloWorld.execute({ name: 'World' });
  console.log(JSON.stringify({ result }));
`;

await sandbox.???('/path/to/script.js', script);

4. What is the default working directory?

• Where does the sandbox start?
• Where should we install npm packages?
• What directories are writable?

5. Complete working example

Please provide a complete, working example that:

1. Creates a sandbox
2. Installs an npm package
3. Writes a script file
4. Runs the script
5. Captures and returns stdout
6. Cleans up

Reference Links

• npm package: https://www.npmjs.com/package/@vercel/sandbox
• Vercel Sandbox docs: https://vercel.com/docs/vercel-sandbox
• Vercel Sandbox SDK reference: https://vercel.com/docs/vercel-sandbox/reference/classes/sandbox

Expected Output

A corrected version of this code that actually compiles and works:

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

export async function executeTool(packageName: string, toolName: string, params: object) {
  const sandbox = await Sandbox.create({ runtime: 'node22' });

  try {
    // Install package
    await sandbox./* correct method */('npm install ' + packageName);

    // Write script
    const script = `
      const pkg = require('${packageName}');
      const result = await pkg['${toolName}'].execute(${JSON.stringify(params)});
      console.log(JSON.stringify({ __result__: result }));
    `;
    await sandbox./* correct method */('/script.cjs', script);

    // Execute and capture output
    const result = await sandbox./* correct method */('node /script.cjs');

    // Parse output
    const output = JSON.parse(result.stdout);
    return output.__result__;
  } finally {
    await sandbox.stop();
  }
}

Our Environment

• @vercel/sandbox: ^1.1.5
• Next.js: ^15.0.0
• TypeScript: ^5.6.0
• Deploying to Vercel