Read Files from the Sandbox

We cloned a repo. Now we should probably look at what we got.

There are two ways to inspect a cloned project from outside the Sandbox: run a shell command and parse the output, or read files directly with the SDK. We're going to do both, because both come in handy.

Outcome

List the cloned repo's contents with ls, read a file with sandbox.readFileToBuffer, and handle the case where the file you wanted doesn't exist.

Fast Track

1. Run ls -la repo and log the output.
2. Read repo/README.md with sandbox.readFileToBuffer.
3. Add a fallback so a missing file doesn't crash the script.

Hands-on exercise

Extend src/sandbox-lifecycle.ts after the clone step:

import { Sandbox } from '@vercel/sandbox';
 
const REPO_URL = 'https://github.com/vercel/examples';
 
async function main() {
  const sandbox = await Sandbox.create({ persistent: false, timeout: 10 * 60 * 1000 });
  console.log(`Sandbox created: ${sandbox.name}`);
 
  const clone = await sandbox.runCommand('git', ['clone', '--depth', '1', REPO_URL, 'repo']);
  if (clone.exitCode !== 0) {
    console.error(`Clone failed: ${await clone.stderr()}`);
    await sandbox.stop();
    return;
  }
 
  const ls = await sandbox.runCommand('ls', ['-la', 'repo']);
  console.log('--- repo contents ---');
  console.log(await ls.stdout());
 
  let readmePreview = '(no README found)';
  const readme = await sandbox.readFileToBuffer({ path: 'repo/README.md' });
  if (readme) {
    readmePreview = readme.toString('utf8').slice(0, 300);
  }
 
  console.log('--- README preview ---');
  console.log(readmePreview);
 
  await sandbox.stop();
}
 
main();

Two things to notice. First, readFileToBuffer accepts a { path } object and resolves to null when the file is missing. Some repos use lowercase readme.md, some put docs in a docs/ folder, and some don't have one at all. A null check keeps the script moving.

Second, we bailed early on a failed clone. Continuing past a failed clone means everything after it fails for confusing reasons. Fail fast, fail loud.

Try It

pnpm tsx src/sandbox-lifecycle.ts

Expected output:

Sandbox created: sbx_7N2k4A...
--- repo contents ---
total 32
drwxr-xr-x  ... .git
-rw-r--r--  ... README.md
-rw-r--r--  ... package.json
drwxr-xr-x  ... examples
--- README preview ---
# Vercel Examples

This repository contains a set of example projects...

If README.md doesn't exist in the repo you're testing, you'll see (no README found) instead of crashing. That's the point.

Commit

git add src/sandbox-lifecycle.ts
git commit -m "feat(sandbox): list directory and read files from sandbox"

Done-When

• ls -la repo returns the cloned directory listing
• sandbox.readFileToBuffer returns the README contents on a real repo
• Missing README logs a warning instead of crashing
• The script still stops the Sandbox at the end

Solution

import { Sandbox } from '@vercel/sandbox';
 
const REPO_URL = 'https://github.com/vercel/examples';
 
async function main() {
  const sandbox = await Sandbox.create({ persistent: false, timeout: 10 * 60 * 1000 });
  console.log(`Sandbox created: ${sandbox.name}`);
 
  const clone = await sandbox.runCommand('git', ['clone', '--depth', '1', REPO_URL, 'repo']);
  if (clone.exitCode !== 0) {
    console.error(`Clone failed: ${await clone.stderr()}`);
    await sandbox.stop();
    return;
  }
 
  const ls = await sandbox.runCommand('ls', ['-la', 'repo']);
  console.log('--- repo contents ---');
  console.log(await ls.stdout());
 
  let readmePreview = '(no README found)';
  const readme = await sandbox.readFileToBuffer({ path: 'repo/README.md' });
  if (readme) {
    readmePreview = readme.toString('utf8').slice(0, 300);
  }
 
  console.log('--- README preview ---');
  console.log(readmePreview);
 
  await sandbox.stop();
}
 
main();