> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Checking a build for remote execution readiness

> Run a Bazel build under a strict local sandbox to find the actions that would fail under remote execution before you enable it.

A remote executor runs each action with only its declared inputs. An action that reads an undeclared file, uses a tool from the host, or reaches the network fails there. A strict local sandbox build finds most of these actions before you enable [remote execution](https://aspect.build/docs/aspect-workflows/platform/features/remote-execution.md).

Run these checks on Linux. The macOS sandbox is less strict, so most of the flags below have no effect there.

## Run the sandbox check

```shell theme={null}
bazel clean --expunge
bazel test //... \
  --keep_going \
  --spawn_strategy=sandboxed \
  --worker_sandboxing \
  --incompatible_strict_action_env \
  --sandbox_default_allow_network=false \
  --incompatible_sandbox_hermetic_tmp \
  --noremote_accept_cached \
  --noremote_upload_local_results \
  --nodisk_cache \
  --test_output=errors \
  --execution_log_compact_file=rbe-ready.exec.log
```

An action that fails here also fails under remote execution.

| Flag | Failure it surfaces |
| - | - |
| `--spawn_strategy=sandboxed`, `--worker_sandboxing` | Reads of undeclared files in the workspace |
| `--incompatible_strict_action_env` | Tools found through the user's `PATH`, and dependencies on user environment variables |
| `--sandbox_default_allow_network=false` | Downloads during the build, and tests that call external services |
| `--incompatible_sandbox_hermetic_tmp` | Actions that share hard-coded `/tmp` paths |
| `--noremote_accept_cached`, `--noremote_upload_local_results`, `--nodisk_cache` | Failures a cache hit would otherwise hide |
| `--keep_going` | Collects every failure in one run |

`--incompatible_sandbox_hermetic_tmp` requires Bazel 7 or later. It's the default from Bazel 8.

## Run the hermetic sandbox check

The first check still mounts `/usr` and `/lib` read-only, so actions that use host system libraries or a host compiler pass it. This run hides them:

```shell theme={null}
bazel test //... \
  --keep_going \
  --experimental_use_hermetic_linux_sandbox \
  --incompatible_strict_action_env \
  --sandbox_default_allow_network=false \
  --noremote_accept_cached \
  --noremote_upload_local_results \
  --nodisk_cache
```

`--experimental_use_hermetic_linux_sandbox` exposes only declared inputs to each action. Every failure names something that the build must declare or that the remote execution image must provide. Expect failures from auto-detected host toolchains, such as the default C++ toolchain. A [hermetic toolchain](https://aspect.build/blog/hermetic-c-toolchain) removes them.

## Fix the common failures

| Failure | Fix |
| - | - |
| Missing system library, such as `libssl` or `libtinfo` | Add the library to the remote execution image, or build it with Bazel |
| Tool not found on `PATH` | Declare the tool as a dependency or toolchain |
| Network access denied | Fetch the file as an external repository, or tag the test `requires-network` |
| Test binds a fixed port | Have the test request a free port at runtime |
| Test needs Docker | Tag the test `no-remote-exec` |

To find actions that produce different outputs between builds, compare the execution logs of two clean builds with [execlog-diff](https://github.com/aspect-build/execlog-diff). Non-deterministic actions cause remote cache misses, but they don't fail under remote execution.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.