Open-source project
roadrunner-server/roadrunner avatar
roadrunner-server/roadrunner

RoadRunner: a Go process manager that makes PHP workers long-lived

🤯 High-performance PHP application server, process manager written in Go and powered with plugins

8,530 stars425 forksGoMIT

At a glance

What is it?
RoadRunner keeps PHP workers alive between requests and drives them with plugins for queues, key-value stores, gRPC, Temporal and WebSockets, replacing the Nginx plus FPM arrangement. Configuration is one YAML file.
Who is it for?
Adopt RoadRunner if your PHP application spends its time in framework bootstrap rather than in application logic, because keeping workers resident between requests is the entire point and it is where the gain comes from. Skip it if your deployment is managed PHP-FPM with a separate worker process, since that arrangement already separates the web tier from the queue consumers and changing it buys little.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • roadrunner-server/roadrunner8,530 ★ · +23
Star history
Repository2026-09-222026-11-15
roadrunner-server/roadrunner8.5k8.5k

23 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Long-lived workers are the whole idea, and everything else is a plugin

RoadRunner is a process manager written in Go that runs PHP as a service. The framing is that it replaces the traditional Nginx plus FPM arrangement, and the mechanism is that a PHP worker stays resident and handles request after request instead of being started per request.

That is a real architectural change rather than a tuning knob. Under PHP-FPM the web server owns process lifecycle and your application code is called once per request inside a process that then goes away. Under RoadRunner the worker process is started once, and what your code must tolerate is that state persists between requests: globals, static caches and any connection you opened stay alive.

So the migration question is not performance, it is whether your code is written to be resident. Code that assumes a clean process per request, or that leaks memory across requests, behaves differently here, and that difference is invisible until load.

The plugin set is what makes it more than a supervisor. Queues have drivers for RabbitMQ, Kafka, SQS, Beanstalk, NATS and in-memory. Key-value storage has Redis, Memcached, BoltDB and in-memory. There is a gRPC server, OpenTelemetry protocol support over gRPC, http and jaeger, a Temporal-backed workflow engine, a distributed lock plugin, a metrics server, WebSockets through a Centrifugo server, and a systemd-like services manager with auto-restarts and an execution time limiter.

The point of listing them is the shape: an application that would otherwise need a separate daemon for each of those now has one binary and one configuration file.

Configuration is one YAML file, and the rpc block is the part to understand

The sample configuration is the clearest description of the architecture.

yaml
version: '3'

rpc:
  listen: tcp://127.0.0.1:6001

server:
  command: "php worker.php"

http:
  address: "0.0.0.0:8080"

logs:
  level: error

The server block names the command that starts it, php worker.php, so your worker is an ordinary PHP script you write and can run and inspect.

The http block is RoadRunner's own listener, separate from the rpc channel, and it binds 0.0.0.0:8080. Note that the rpc listener binds 127.0.0.1, which is the right default: an RPC endpoint should not be reachable from outside the machine.

That separation is a security property worth stating explicitly. The rpc listener is effectively an administrative channel into RoadRunner, and the sample configuration puts it on loopback. Changing it to 0.0.0.0 without understanding what speaks that protocol is the kind of edit that turns a performance decision into an exposure.

The full sample lives at .rr.yaml in the repository root, which is where you should look rather than inferring the shape from the snippet.

Five install routes, and the extension requirements differ between them

Installation is the part of this project with the most variants, and the differences between them are about what you need installed on the machine.

The easiest route is a pre-built release binary, available for macOS, Linux, FreeBSD and Windows, with instructions on the GitHub releases page. The Docker route copies the binary out of the published image:

dockerfile
FROM ghcr.io/roadrunner-server/roadrunner:3.0.0 AS roadrunner
FROM php:8.3-cli

COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr

The Composer route is the one with requirements worth reading twice:

bash
composer require spiral/roadrunner-cli
./vendor/bin/rr get-binary

php-curl and php-zip are needed to download the binary automatically, and php-sockets is needed to run RoadRunner at all. The README tells you to check with php --modules.

The remaining routes are single commands: a Debian package via wget and dpkg -i for Ubuntu and its derivatives, a curl script that pipes a shell script from the repository, brew install roadrunner on macOS, and choco install roadrunner on Windows.

So the choice is not really which package manager you prefer. The Composer route is the one that ties the binary to your project's dependencies, which is convenient until it is also the one that fails on a host missing an extension. The curl-pipe route is the one to think about twice, since it executes a script fetched at the moment you run it.

The plugin surface is a maintenance surface, and the version line is dated

Two things about this project's shape determine how you evaluate it.

The first is that a plugin is a separate codebase with its own upstream. A queue driver for Kafka is a Kafka client, and one for SQS is an AWS SDK. Each brings its own release cadence, its own breaking changes and its own failure modes. The plugin list in the README is therefore also an inventory of dependencies you are choosing to inherit.

The version scheme is the second. The project has moved from year-named tags, the last being v2025.1.15 in June 2026, to semantic versions: v3.0.0 was released on 2026-10-09 and v3.0.1 on 2026-10-21. The Go module path is github.com/roadrunner-server/roadrunner/v3, so the major version is carried in the import path.

A tag alone does not tell you whether a release line still receives fixes. The repository links a release schedule project board, and that is where the answer lives. Anyone planning a long-lived deployment needs to read it, because the tag alone will not tell you how long this branch is supported.

The repository itself is not archived, was last pushed on 2026-11-01, is MIT licensed, and carries coverage and CI badges alongside links to the documentation site, the forum and a Discord server. The Go module targets a current toolchain, and the project describes itself as production-ready, which is a claim about its own status rather than a compatibility statement.

HTTP/3 and 103 Early Hints are listed, and they need context

The HTTP plugin list includes automatic TLS management, 103 Early Hints support, and middleware for static files, headers, gzip, prometheus metrics, send for x-sendfile, OTEL and proxy_ip_parser.

Automatic TLS management is the significant one for deployment. It means RoadRunner can obtain and renew certificates rather than requiring your web server to front it with a certificate, which is part of what lets it replace Nginx plus FPM rather than sit behind them. If your existing setup terminates TLS at the edge, you would keep that and not use this.

103 Early Hints is a performance feature for connections where the first request is slow to produce a response, typically because of a cold cache. The server can send a hint before the final response so the client starts fetching a second resource early. It only helps in that specific situation, and it requires client support, so it is worth knowing it exists rather than assuming it applies to your traffic.

The middleware list is where the practical detail is. gzip and headers are ordinary. prometheus metrics and OTEL are how you observe the thing. proxy_ip_parser matters whenever your application reads the client IP from a header, because behind any reverse proxy that header is set by the proxy and is trivially spoofed if the proxy does not overwrite it.

The gRPC server mentions that the protobuf extension can be used for increased speed, which is an honest note that the faster path costs you a PHP extension.

Where the worker model stops being the right answer

Four boundaries.

The resident-worker requirement is the one that catches people. Code that accumulates state between requests will keep accumulating, because nothing resets the process for you. That is a correctness issue under load rather than at startup, and it is the first thing to measure after switching.

php-sockets is a hard requirement, not a recommendation. A host without that extension cannot run RoadRunner at all, which narrows the deployment targets compared with PHP-FPM in environments where you do not control the extension set.

The rpc listener is an administrative channel that the sample binds to loopback. Anything that binds it more widely is exposing a control surface, and that has to be a deliberate decision rather than a copy-paste edit of the address.

The Temporal and Centrifugo integrations are dependencies on other projects. A workflow engine and a WebSocket broker have their own operational requirements, their own version compatibility and their own failure modes, and pulling them in through RoadRunner does not remove any of that.

There is also the honest comparison with what you already have. If you run PHP-FPM behind Nginx with separate worker processes for queues, you already have the separation RoadRunner provides, and you gain the resident workers. If you are on a platform with managed PHP where you cannot keep processes resident, RoadRunner is not available to you at all.

For evaluation, the practical test is a resident-worker profile: run a realistic request mix against one worker for an extended period and watch memory. That measurement tells you more than any benchmark of requests per second, because the resident model fails on accumulation and a throughput number will not show it.

Editorial conclusion

Adopt RoadRunner if your PHP application spends its time in framework bootstrap rather than in application logic, because keeping workers resident between requests is the entire point and it is where the gain comes from. Skip it if your deployment is managed PHP-FPM with a separate worker process, since that arrangement already separates the web tier from the queue consumers and changing it buys little. Before switching, confirm your hosts have the php-sockets extension, since the project requires it to run at all, and read the release schedule rather than the tags: a tag does not tell you which maintenance releases are still supported.

Frequently asked questions

How do I install RoadRunner?

The easiest route is a pre-built release binary for macOS, Linux, FreeBSD or Windows from the GitHub releases page. Composer users run composer require spiral/roadrunner-cli followed by ./vendor/bin/rr get-binary, which needs the php-curl and php-zip extensions. Debian derivatives can install a .deb package, macOS has brew install roadrunner, and Windows has choco install roadrunner.

What replaces Nginx and PHP-FPM in RoadRunner?

RoadRunner is a process manager written in Go that keeps PHP workers alive between requests instead of starting one per request, and it serves HTTP itself. It adds plugins for queues including RabbitMQ, Kafka, SQS, Beanstalk and NATS, key-value stores including Redis, Memcached and BoltDB, gRPC, OpenTelemetry, Temporal workflows, distributed locks, metrics and WebSockets through Centrifugo.

What PHP extensions does RoadRunner need?

php-sockets is required to run RoadRunner at all. Separately, the Composer install route needs php-curl and php-zip to download the binary automatically. The README suggests checking what is present with php --modules. The gRPC server can use the protobuf extension for increased speed, which is optional.

How does RoadRunner configure its PHP worker?

Configuration lives in .rr.yaml, and the sample shows an rpc block listening on tcp://127.0.0.1:6001, a server block with command "php worker.php", an http block binding 0.0.0.0:8080, and a logs block. The full sample is at .rr.yaml in the repository root.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. roadrunner-server/roadrunner on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/roadrunner-server-roadrunner.svg)](https://hysenlabs.com/projects/roadrunner-server-roadrunner)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/roadrunner-server-roadrunner.svg)](https://hysenlabs.com/projects/roadrunner-server-roadrunner)

Was this useful?