Remote Execution

Remote execution in Once means that the script contract stays in the repository while the process runs in a fresh environment supplied by an infrastructure provider.

The important boundary is the action, not the test framework. Vitest is the program being run. Microsandbox, E2B, and Daytona are execution providers.

What Moves To The Machine

For each remote action, Once performs this lifecycle:

1. Resolve the named provider and immutable image or template.
2. Create a fresh sandbox.
3. Package only the declared input files, directories, executable modes, and safe symbolic links.
4. Transfer that package into a clean /workspace directory.
5. Run the declared argument list with its working directory, selected environment variables, resources, and timeout.
6. After a successful exit, retrieve only the declared outputs into a local staging area and validate them before installation.
7. Delete the sandbox, whether the action succeeded or failed.

Provider access keys configure the transport. They are not placed in the action environment or included in the action identity.

Run Real Vitest Tests

Treat dependency installation and testing as separate actions. The install script uses the npm package manager, consumes the package manifests, and produces 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 --no-audit --no-fund

The test script depends on that action and consumes its output:

#!/bin/sh
# once needs "./install.sh"
# once input "../src"
# once input "../tests"
# once output "../reports"
# once cwd ".."
# once remote "remote_tests"

./node_modules/.bin/vitest run \
  --reporter=json \
  --outputFile=reports/vitest.json

The provider environment supplies Node.js, npm, and basic operating-system tools. The install action supplies the exact repository dependencies. Its node_modules output becomes a declared input to the test action, including package-manager symbolic links and executable modes.

This split means a package-lock change invalidates installation. A source or test change invalidates the test action without forcing installation to run again.

Choose A Provider

Use Microsandbox to test the contract on a supported local computer. Use E2B when you have a prepared hosted template. Use Daytona when you want Once to start from a container image.

All three adapters implement the same declared input and output boundary. E2B and Daytona use one archive for each transfer so large dependency trees do not require one network request per file. The hosted image or template must provide tar for unpacking and packing those archives.

Machine Cleanup

Once waits for provider deletion after every normal success or failure. It also schedules deletion if the executing task is cancelled while a Tokio runtime is still active.

The hosted providers add a second line of defense:

• E2B receives a finite lifetime and a kill-on-timeout policy.
• Daytona receives an ephemeral policy with immediate deletion after stop.

If the provider refuses a delete request after an otherwise successful action, Once reports the action as failed. On an action failure, Once preserves the original failure and records a cleanup failure in its internal log.

How This Compares With Bazel

Bazel remote execution asks which content-addressed values are missing and uploads only those values. That is the right transport for a large shared worker fleet because unchanged files do not cross the network again.

The E2B and Daytona adapters currently upload one complete archive of the declared inputs for each cache miss. This gives Once the same correctness boundary, but it is not yet as bandwidth-efficient as Bazel. The provider interface leaves room for a missing-content exchange so a future adapter can deduplicate files without changing script annotations.

Once also keeps the executor boundary wider than the Bazel protocol. A local micro-virtual-machine, a hosted sandbox service, and a content-addressed worker fleet can all consume the same prepared action.