Run GitHub Actions in a microVM

Start GitHub’s official Actions runner image in a microsandbox, let it accept one job, then remove the VM. The runner is ephemeral, so GitHub deregisters it after that job.

Before you start

Authenticate the GitHub CLI for the target repository. The token needs Administration: write to create the temporary runner and Actions: write to start the workflow. Set the repository once for the commands below:

repo=OWNER/REPOSITORY

$repo = 'OWNER/REPOSITORY'

Add the workflow

Add this file to the repository’s default branch. Replace the final step with the commands you want the runner to execute.

.github/workflows/microsandbox-runner.yml

name: Microsandbox runner

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  test:
    runs-on: [self-hosted, msb-ephemeral]
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - run: test -f README.md && uname -a

Run one job

Queue the workflow

The job waits until the temporary runner connects.

gh workflow run microsandbox-runner.yml --repo "$repo"

Create the runner VM

Give this runner a unique name so multiple jobs can run independently.

runner="msb-gh-$(date +%s)"
msb create ghcr.io/actions/actions-runner:2.336.0 \
  --name "$runner" --cpus 2 --memory 4G --max-duration 1h

$runner = "msb-gh-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
msb create ghcr.io/actions/actions-runner:2.336.0 `
  --name $runner --cpus 2 --memory 4G --max-duration 1h

First, ask GitHub to register this VM as a runner for one job. GitHub returns a single-use configuration containing the repository address, runner identity, labels, and temporary credentials.

runner_config=$(gh api --method POST --hostname github.com "repos/$repo/actions/runners/generate-jitconfig" \
  -f name="$runner" -F runner_group_id=1 -f 'labels[]=self-hosted' \
  -f 'labels[]=msb-ephemeral' -f work_folder=_work --jq .encoded_jit_config)

$runnerConfig = gh api --method POST --hostname github.com "repos/$repo/actions/runners/generate-jitconfig" `
  -f "name=$runner" -F runner_group_id=1 -f 'labels[]=self-hosted' `
  -f 'labels[]=msb-ephemeral' -f work_folder=_work --jq .encoded_jit_config

Next, pass that configuration through standard input to GitHub’s runner process inside the microVM:

printf '%s\n' "$runner_config" | msb exec --stream --user runner \
  --workdir /home/runner "$runner" -- \
  bash -lc 'read -r config; exec ./run.sh --jitconfig "$config"'
unset runner_config

$runnerConfig | msb exec --stream --user runner `
  --workdir /home/runner $runner -- `
  bash -lc 'read -r config; exec ./run.sh --jitconfig "$config"'
Remove-Variable runnerConfig

The runner now opens an outbound HTTPS long poll to GitHub and waits. No inbound port or public IP is required. GitHub returns the queued job through that request, and the command exits when the job finishes.

Remove the VM

After the job completes, stop and delete the sandbox.

msb stop "$runner"
msb rm "$runner"

msb stop $runner
msb rm $runner

The GitHub credential used by gh stays on the host. Only the single-use JIT configuration enters the VM, and the workflow receives only the permissions declared in its YAML. No host directory or Docker socket is mounted into the runner. To keep accepting jobs, run the same four steps from a long-lived machine or service whenever a matching workflow job is queued. For a larger runner fleet, see GitHub’s self-hosted runner autoscaling guidance.

Agents

CI/CD

Docker

Sandbox Workflows

Automation & Tooling

Data & Observability

Run GitHub Actions in a microVM

Before you start

Add the workflow

Run one job

​Before you start

​Add the workflow

​Run one job

Before you start

Add the workflow

Run one job