Microsandbox

Microsandbox runs a command in an isolated micro-virtual-machine on the local computer. It is useful for validating the same declared input and output contract used by the hosted E2B and Daytona executors.

Configure An Execution Environment

Give the infrastructure a name based on its role. The name is a policy label, not the name of the test framework:

[infrastructures.remote_tests]
kind = "microsandbox"
image = "node:22.18.0-alpine"

[infrastructure.execution]
provider = "remote_tests"

The provider definition selects the Microsandbox executor adapter and the image that supplies tools such as Node.js. Pin the image to an immutable digest for reproducible shared workflows.

Run one command through the configured provider:

once exec --remote -- node --version

Select The Provider From A Script

An annotated script can name the same infrastructure directly:

#!/bin/sh
# once remote "remote_tests"
# once input "../src"
# once input "../tests"
# once output "../coverage"
# once cwd ".."

./node_modules/.bin/vitest run

Once resolves remote_tests through the root manifest. The command uses the Node.js executable from the configured image. Once does not copy a machine-specific interpreter path or import the host tool environment.

Model Package Dependencies As An Action

The image should contain tools that are stable across many actions. Repository dependencies belong in the action graph. For example, an install script can use the npm package manager to produce node_modules:

#!/bin/sh
# once input "../package.json"
# once input "../package-lock.json"
# once output "../node_modules"
# once cwd ".."
# once remote "remote_tests"

npm clean-install

The test script then declares the install script as a dependency:

# once needs "./install.sh"

Once runs the install action first. Its declared node_modules output becomes a declared input of the test action and contributes to that action's cache identity. A cache hit can restore the dependency output without running the installer again.

This is preferable to copying the host's node_modules by default. Package trees can contain platform-specific native files and symbolic links into a package manager store. If an existing workflow must copy such a tree, declare it as an input; Once transfers it recursively and rejects symbolic links that escape the declared input trees.

Filesystem Boundary

The Microsandbox executor starts with a clean workspace. Before execution, Once creates the declared working directory and transfers only declared input files, directories, and safe symbolic links. After a successful command, Once retrieves only declared outputs and installs them into the workspace through a staging directory.

The local adapter streams these trees through the Microsandbox filesystem service. Hosted E2B and Daytona adapters package the same declared trees into archives for transfer. A future hosted executor can use a content-addressed missing-file exchange without changing the script contract.

Once stops the micro-virtual-machine and removes its persisted state after success, failure, or timeout.

Microsandbox is currently available through Once on Linux and Apple Silicon macOS.