Velox

Velox builds a custom RoadRunner binary from the plugin list in velox.toml. It downloads the RoadRunner source for the requested ref, renders container/plugins.go, applies the requested plugin versions plus any replace and exclude directives through go mod edit, runs go mod tidy, and compiles the binary with go build.

Documentation: docs.roadrunner.dev/customization/build.

go install github.com/roadrunner-server/velox/v3/cmd/vx@v3.0.0-beta.1

Install the exact tag. The /v3 module line has only pre-release tags for now, so @latest has no stable release to resolve to.

Migration: releases before v3 install from github.com/roadrunner-server/velox/v2025/cmd/vx.

docker pull ghcr.io/roadrunner-server/velox:3.0.0-beta.1

Images are published to ghcr.io/roadrunner-server/velox and spiralscout/velox; the image tag is the release tag without the leading v. The entrypoint is vx, and the image ships the sample config at /etc/velox.toml.

docker run --rm \
  -e GITHUB_TOKEN \
  -v "$PWD/velox.toml:/etc/velox.toml" \
  -v "$PWD:/output" \
  ghcr.io/roadrunner-server/velox:3.0.0-beta.1 build -c /etc/velox.toml -o /output

The docker-compose.yml in this repository builds the image from source and runs build -c=/etc/velox.toml -o=/tmp/; uncomment the volume mapping there to copy the produced binary to the host.

vx build -c velox.toml -o .

• -c, --config: path to the configuration file, default velox.toml.
• -o, --out: output directory for the produced rr binary, default the current directory.
• --version: velox version and build time.

Both flags are persistent, so vx -c velox.toml build -o . works as well. The build downloads the RoadRunner source into a temporary directory that is removed when the command returns.

[roadrunner]
ref = "master"

[github.token]
token = "${GITHUB_TOKEN}"

[log]
level = "debug"
mode = "production"

[plugins.logger]
tag = "latest"
module_name = "github.com/roadrunner-server/logger/v6"

[plugins.server]
tag = "latest"
module_name = "github.com/roadrunner-server/server/v6"

[plugins.rpc]
tag = "latest"
module_name = "github.com/roadrunner-server/rpc/v6"

[plugins.http]
tag = "latest"
module_name = "github.com/roadrunner-server/http/v6"

The velox.toml shipped in this repository is the full sample: it lists every plugin that RoadRunner master registers.

• ref: tag, branch, or 40-character commit SHA of roadrunner-server/roadrunner. Default master. A valid semver value (v2025.1.7) downloads refs/tags, a 40-character hex value downloads that commit, anything else downloads refs/heads.

• base_url: GitHub host, default https://github.com. Set it to a GitHub Enterprise host (https://ghe.example.com) to download the source from a private installation; the archive paths and the Authorization header are the same as on github.com. Only the host is configurable: the mirror must live at <base_url>/roadrunner-server/roadrunner.
• token: personal access token used for the download. ${ENV_VAR} is expanded from the environment. It is sent as a bearer Authorization header and dropped on a redirect to another host.

• os: target GOOS, default the host GOOS. windows is rejected.
• arch: target GOARCH, default the host GOARCH.

Either key may be omitted on its own; the host value fills it. Every build reuses the caller module and build caches (Go keys build cache entries by target). A cross build skips the rr --version smoke test.

• level: debug, info, warn, or error.
• mode: production, development, raw, or none (off is an alias). Default when the section is absent: level debug, mode development.

• enabled: compiles with -gcflags "all=-N -l" -tags debug and keeps the symbol table for a debugger.
• race: compiles with -race (sets CGO_ENABLED=1). Requires a C toolchain for the target platform. The Docker image includes GCC and musl development headers for native Linux builds.

• module_name: full Go module path of the plugin, including the major-version suffix; each module may be listed once.
• tag: semver version to require, or a non-semver ref (latest, a branch, a commit) that skips the post-tidy version check.

informer and resetter are compiled in from the versions the downloaded RoadRunner requires. Listing either of them here is skipped with a warning, because a user entry would register the plugin twice.

Maps to a go.mod replace directive applied before go mod tidy.

[[replaces]]
new = "../local-fork"
old = "github.com/foo/bar"

[[replaces]]
new = "github.com/me/bar-fork@v1.2.3-patched"
old = "github.com/foo/bar@v1.2.3"

• Both fields are single strings; embed the version inline with @.
• A local path in new (., .., ./, ../, or absolute) must not carry an @version. An @ inside a directory name is fine: only a trailing @<semver> counts as a version.
• Neither field may contain =.
• old must be unique across the list.
• A relative local path in new resolves against the working directory of vx, not against the downloaded source tree.

Maps to a go.mod exclude directive applied before go mod tidy.

[[excludes]]
module = "github.com/redis/go-redis/v9"
version = "v9.15.0"

• version must be a canonical semver version (v9.15.0, not v9.15) whose major matches the module path (/v9 needs v9.x.y).

• Supported: RoadRunner master (the v2025 module line) with the /v6 beta plugins. RoadRunner v2025.x releases pair with the /v5 plugins.
• All plugins in one build must share the same major version: http/v6 with logger/v6, never http/v6 with logger/v5.
• Do not point plugins at a master branch.

• Windows build targets are not supported in velox v3.
• Pin plugin tags for reproducible builds. A tag that is not a semver version (latest, a branch, a commit) skips the post-tidy version check, so the resolved version depends on when the build runs.
• Plugins are registered in module-path order, so the same plugin set renders the same container/plugins.go.
• Each build compiles the binary in a unique temporary directory inside the output directory. The binary is renamed to rr after rr --version prints the requested ref; a cross build skips that check.
• -trimpath is always set, and SOURCE_DATE_EPOCH is honored for the injected build timestamp.

• RoadRunner build documentation
• Discord community