Install packages

You can add packages to a template ahead of time or install them after a sandbox starts. Pin versions in both cases to keep the environment reproducible.

Add packages to a template

Use this option when every sandbox needs the same dependencies. The SDK provides dedicated pipInstall, npmInstall, bunInstall, and aptInstall methods. The example below adds Python and Node.js packages, builds a template, and starts a sandbox from it.

import { Sandbox, Template } from "@abox-dev/sdk";

const templateName = process.env.TEMPLATE_NAME ?? "custom-packages";
const template = Template()
  .fromTemplate("base")
  .pipInstall("cowsay==6.1")
  .npmInstall("lodash@4.17.21");

await Template.build(template, templateName);

const sandbox = await Sandbox.create(templateName);

try {
  const result = await sandbox.commands.run(
    "python3 -c 'import cowsay; print(cowsay.__version__)' && " +
      "node -e 'console.log(require(\"lodash/package.json\").version)'",
  );
  console.log(result.stdout);
} finally {
  await sandbox.kill();
}

The template name must be unique within the project. Use TEMPLATE_NAME to set it without changing the program.

Install a package at runtime

Use this option for a one-off dependency. The package exists only in the current sandbox and is not added to future runs of the base template.

import { Sandbox } from "@abox-dev/sdk";

const sandbox = await Sandbox.create();

try {
  const result = await sandbox.commands.run(
    "python3 -m pip install --disable-pip-version-check --no-cache-dir 'cowsay==6.1' >/dev/null && " +
      "python3 -c 'import cowsay; print(cowsay.__version__)'",
    { timeoutMs: 120_000 },
  );
  console.log(result.stdout.trim());
} finally {
  await sandbox.kill();
}

The dedicated package-install methods apply while building templates. In a running sandbox, invoke an available package manager through commands.run. Package-manager availability depends on the selected template.