Sandboxing

Sandboxing is essential to make sure all builds and tasks are insulated from the machine they run in. In Minimal, all tasks and builds run in a sandbox.

Package builds

Minimal packages encapsulate all tooling and software, so it’s essential they are compiled in a hermetically-sealed environment that gives the rest of the ecosystem a strong foundation. As such, package builds take place in a cleanroom sandbox that shares nothing with the host machine, aside from network access when a dependency calls for it.

Specifically, the cleanroom sandbox wires:

  • Files representing the build inputs and runtime dependencies of the package
  • Working directories /build, /tmp, and an empty /state.
  • The source of the package being built
  • Network connectivity (when called-for by a dependency)

At the completion of the build, artifacts are gathered based on the outputs specified in the packages’ build-spec, and are cached for later consumption when needed by a task or another package build.

By default, Minimal is configured to fetch completed builds from our binary cache, to avoid a slow process building everything locally the first time it is needed. You can force builds to run locally with the build CLI’s --no-fetch and --no-cache flags.

The task sandbox

When a task is invoked, its configuration is used to setup and launch a task sandbox. This sandbox wires:

  • Files representing the packages requested and their runtime dependencies. The packages requested for a task includes any that are explicitly defined on the task, those defined on the task’s profile (or the default profile if set), and those defined by the repository stack (if set).
  • The repository’s files and directories, from the repository root downward, but not above it.
  • A /state directory, which can be shared between tasks and task invocations by specifying a task state_key. Package managers are typically wired to cache source downloads and intermediate build artifacts in this directory.
  • Pinhole filesystem mappings, as declared by packages.
  • Network connectivity when necessary.

The session sandbox

A session is hosted in a sandbox of its own: the one you drop into when you attach a shell. Its contents are the union of the project’s [session] packages, the packages the repository’s [stack] declares, and whatever your applied loadouts contribute. The session sandbox’s working directory is the session’s workspace, seeded with a copy of your project files at activation.