3.3. Running Your Own Runner#

To execute virtual prototypes on your own machines while still using the SimBricks Cloud for management and scheduling, you set up your own Runners. A Runner registers itself with the Backend under your namespace; the Backend then schedules matching Runs onto it.

3.3.1. Register the Runner#

First, create the Runner on the Backend to obtain its id, e.g. via the CLI (see Command Line Interface (CLI)):

simbricks-cli runners create <resource_group_id> <label> [<tags>...]

The tags you assign here are matched against the runner_tags of submitted Fragments.

3.3.2. Option 1: Docker (recommended)#

The easiest way to run a Runner is the pre-built image (see Using Pre-Built Docker Images). The entrypoint expects your namespace and the runner id as arguments:

docker run --rm -it --device /dev/kvm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    simbricks/simbricks-runner <NAMESPACE> <RUNNER_ID>

By default the Runner is configured with a single local fragment executor (executing simulations in the Runner’s own environment). To have the Runner spawn executions in simbricks/simbricks-executor containers instead, configure the Docker plugin (below).

3.3.3. Option 2: Bare metal#

Install the runner package and the simulators you want to offer from the conda channel:

micromamba install simbricks-runner simbricks-qemu-sim-bin ...  # etc.
simbricks-runner --configuration_file runner_config.yaml

The Runner reads its settings from environment variables / a runner.env file (namespace, runner id, backend URL — the defaults point to https://app.simbricks.io/api) and its fragment executors from a YAML configuration file.

3.3.4. Fragment executor configuration#

The configuration file declares which fragment executors the Runner offers. Each entry has a tag (selectable from scripts via fragment.fragment_executor_tag) and a plugin:

fragment_executors:
  - base_executor:
      plugin: simbricks.runner.main_runner.plugins.local_plugin
  - corundum_executor:
      plugin: simbricks.runner.main_runner.plugins.docker_plugin
      docker_image: "my-registry/my-corundum-executor"
      docker_pull: true

The local plugin spawns simbricks-executor-local directly in the Runner’s environment — all simulators of the fragment must be installed there.
The docker plugin spawns the fragment inside a container (default image simbricks/simbricks-executor); images can be restricted via allow/deny lists and extended with additional docker_opts. The container is started with --device=/dev/kvm, so the host needs KVM access for fast QEMU runs.

Hardware/OS requirements are the same as for the executor image (see Using Pre-Built Docker Images): /dev/kvm for QEMU, kernel.perf_event_paranoid <= 1 for gem5, and network access to https://disk-images.simbricks.io for the images SimBricks publishes (The images SimBricks publishes). Images of your own go under the global input directory, which you provide and point GLOBAL_INPUT_DIR at — see The global input directory.

3.3.5. Runner settings and the image cache#

Beyond the fragment executor list, the Runner and its fragment executors are configured through environment variables, or a runner.env file next to the Runner:

Variable	Meaning
`GLOBAL_INPUT_DIR`	Where prebuilt disk images and their boot artifacts are found (The global input directory). Not needed for the images SimBricks publishes, which are downloaded.
`IMAGE_CACHE_DIR`	Where images built or downloaded for a run are kept for later runs. Unset puts the cache beside the run work directories, in `./runner-work/.image-cache`.
`IMAGE_CACHE_ENABLED`	`false` turns caching off entirely: every run builds and downloads its images again.
`IMAGE_CACHE_SIZE`	How large that may grow, e.g. `200G`. Defaults to `50G` for the default directory; a directory named through `IMAGE_CACHE_DIR` grows without bound unless this is set.
`IMAGE_CACHE_COMPRESSION`	`zstd` (the default), `zlib` for a QEMU too old to read zstd, or `none`. An unknown name is rejected when the executor starts.

Reusing builds across runs describes what the cache does for a run. Its directory is kept across runs, outside their working directories, and is content-addressed and rebuilt on demand, so it can be deleted while the Runner is idle.

With the local plugin the fragment executor inherits the Runner’s environment, so the default cache directory persists between runs. The docker plugin starts a container per fragment, with --rm, so the default cache inside it is discarded with the container: to keep one, mount a directory from the host and name it through docker_opts:

fragment_executors:
  - base_executor:
      plugin: simbricks.runner.main_runner.plugins.docker_plugin
      docker_opts:
        - "-v"
        - "/var/cache/simbricks-images:/image-cache"
        - "-e"
        - "IMAGE_CACHE_DIR=/image-cache"
        - "-e"
        - "IMAGE_CACHE_SIZE=200G"

Several Runners can share one cache directory, including over a network filesystem. Entries are locked while they are built, so two Runners wanting the same image wait for one build rather than running two, and an entry that another machine evicts between being looked up and being read is treated as a miss instead of failing the run. Eviction leaves alone whatever a run is currently holding.