Read files out of a sandbox

Browse all recipes

Read build results, inspect project files, or copy data out before deleting a sandbox. Start with a running sandbox handle and an absolute path inside it.

The examples return content to your application. To keep it on your machine, write the received bytes to a local file.

List a directory

Walk the directory through the file collection's iterator. It follows pagination and returns the entries. Listing gives metadata, not file content.

return sandbox.files.all(path).collect();

import type { Sandbox } from '@docker/sandboxes';

export async function listDirectory(sandbox: Sandbox, path: string) {
  return sandbox.files.all(path).collect();
}

Read a small text file

Use the bounded read helper for text you want in memory. The example limits the read to one MiB. Choose a bound that fits your application's memory budget, or download a larger file as a stream.

return sandbox.files.read(path, {
  encoding: 'utf8',
  maxBytes: 1024 * 1024,
});

import type { Sandbox } from '@docker/sandboxes';

export async function readFile(sandbox: Sandbox, path: string) {
  return sandbox.files.read(path, {
    encoding: 'utf8',
    maxBytes: 1024 * 1024,
  });
}

Inspect a path

Read metadata before deciding whether to download, move, or remove a path. A successful metadata read does not reserve the file: another process may change it afterward.

return sandbox.files.stat(path);

import type { Sandbox } from '@docker/sandboxes';

export async function statFile(sandbox: Sandbox, path: string) {
  return sandbox.files.stat(path);
}

Download a file as a stream

Pass the sandbox path and a callback or writer that consumes bytes. The example closes the transfer when it finishes or fails.

Treat the download as complete only when it ends successfully. If it fails halfway through, discard or separately identify the partial local file before retrying.

const download = await sandbox.files.download(path);
try {
  for await (const chunk of download) write(chunk);
} finally {
  await download.close();
}

import type { Sandbox } from '@docker/sandboxes';

export async function downloadFiles(
  sandbox: Sandbox,
  path: string,
  write: (bytes: Uint8Array) => void,
) {
  const download = await sandbox.files.download(path);
  try {
    for await (const chunk of download) write(chunk);
  } finally {
    await download.close();
  }
}

Move a path

Pass the current path and destination. This moves data inside the sandbox; it does not download anything to your computer.

await sandbox.files.move(from, to);

import type { Sandbox } from '@docker/sandboxes';

export async function movePath(
  sandbox: Sandbox,
  from: string,
  to: string,
) {
  await sandbox.files.move(from, to);
}

Remove a path

Remove a file, or enable recursive removal for a directory tree. Check the result for a failed path rather than assuming that every requested removal succeeded.

Recursive removal is destructive. Keep user-supplied paths constrained to the directory your application owns.

const result = await sandbox.files.remove(path, { recursive });
if (result.failedPath)
  throw new Error(`Remove ${path} stopped at ${result.failedPath}`);

import type { Sandbox } from '@docker/sandboxes';

export async function removePath(
  sandbox: Sandbox,
  path: string,
  recursive: boolean,
) {
  const result = await sandbox.files.remove(path, { recursive });
  if (result.failedPath)
    throw new Error(`Remove ${path} stopped at ${result.failedPath}`);
}