Skip to content
Scalpels home

Sign up now for $10 in credit on a new Laravel Cloud account.

Experiment

We served Laravel routes from a Go binary on Laravel Cloud

· Claude Code

The question in the idea was whether a Go or Rust binary can live inside a Laravel app on Laravel Cloud and answer a few routes before PHP or the framework is involved. A Laravel route that forwards to the binary does not count, because PHP has already done the work we wanted to skip.

The answer is yes, on both of the web servers Cloud uses for PHP apps. We tested it on a live Cloud app on 15 November with a small Go server and four deployments. Neither approach is supported by Laravel, and both lean on details of Cloud's images that could change without notice.

The test app is public at artisan-build/cloud-binary-routing-experiment. The tag option-2-nginx is the Nginx version. The main branch, also tagged option-1-octane, is the Octane version. The files that matter are cloud/nginx-inject.sh, config/octane.php, fastpath/main.go, and routes/web.php. A coding agent did the work from written briefs, and we checked its results against the live app.

The Octane version is still running. /fast/ping comes from Go, and /php is the PHP control. The app sleeps when it is idle, so the first request can be slow.

How a request reaches a PHP app on Cloud

A request to a Cloud app goes through Cloudflare first. Cloudflare sends it down a Cloudflare Tunnel to Cloud's internal router, which is a proxy built on Nginx. The router passes it to port 8080 in the app's container.

What listens on port 8080 depends on one setting. By default it is Nginx, which hands PHP requests to PHP-FPM, the pool of PHP processes that run each request. With Cloud's Octane toggle on, it is FrankenPHP, a PHP server built on the Caddy web server that keeps the application booted between requests. Cloud writes the configuration for both.

We found no documented way to change that configuration for a PHP app. Cloud's docs say "PHP-FPM uses Nginx. Octane uses FrankenPHP with Caddy instead," and stop there. Other runtimes on Cloud set a start command, the command Cloud runs to start the app. Cloud's API schema says a start command is "prohibited for PHP apps and static websites." So we could not replace Cloud's web server with our own. We had to get a rule into the one Cloud gives us.

The control route

The test app has a Laravel route that answers any request under /fast/ itself.

Route::any('/fast/{any?}', fn () => response()->json([
    'served_by' => 'laravel',
    'path' => request()->path(),
])->header('X-Served-By', 'laravel'))->where('any', '.*');

That makes every response easy to read. If a request for /fast/ping comes back with X-Served-By: laravel, PHP handled it. If it comes back with X-Served-By: go-fastpath, the Go binary did, and PHP never saw it.

A second route, /php, reports which PHP server ran it, fpm-fcgi or frankenphp.

Running the binary next to PHP

The binary is about fifty lines of Go using only the standard library. It answers every path with a JSON description of the request it received, including the client IP and scheme it was told about. It listens on loopback only, on 127.0.0.1 and ::1, so nothing outside the container can reach it directly.

Cloud's PHP image has no Go toolchain, so we did not build it on Cloud. We cross-compiled a static binary for Cloud's ARM machines and committed it to the repository at bin/fastpath.

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w" -o ../bin/fastpath .

The result is a 5.9 MB statically linked executable.

To run it, we added a custom background process with the command ./bin/fastpath. Background processes are the long-running commands Cloud normally uses for queue workers. Ours ran on the App cluster, the compute that also serves web requests. That was the question the whole idea depended on, and the answer was yes. Custom background processes on the App cluster run in the same container as Nginx or FrankenPHP and PHP-FPM, under the same supervisor, a process Cloud calls cloud-init. Everything shares one loopback address.

Our first deployment crashed. The binary started out listening on port 9000, which is the port PHP-FPM uses in Cloud's image. The binary bound the port first, and PHP-FPM could not start.

fastpath: listening on 127.0.0.1:9000
ERROR: unable to bind listening socket for address '127.0.0.1:9000': Address already in use (98)
ERROR: FPM initialization failed
...
App unhealthy after 41.4s, state: crashing

Cloud aborted the deployment. We moved the binary to port 7070 and it has not clashed with anything since.

Option A uses Nginx and PHP-FPM

This one works, and it is the more fragile of the two.

We ran a probe script as the build command to see what the build could reach. Cloud had already written the Nginx server config, /etc/nginx/conf.d/default.conf, before the build command started. The file is owned by root, so the build cannot edit it in place. But the build runs as www-data, and www-data owns the conf.d directory. A user who owns the directory can delete a file in it and write a new one with the same name.

So our build command runs a script, cloud/nginx-inject.sh, that copies the config, inserts one location block, deletes the original, and writes the new version in its place. The block goes right after the server's listen 8080 line.

location ^~ /fast/ {
    proxy_pass http://127.0.0.1:7070;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $http_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $cloud_forwarded_proto;
    add_header X-Fastpath-Via nginx always;
}

The ^~ modifier makes this prefix win over the \.php$ rule that sends requests to PHP-FPM. $cloud_forwarded_proto is a variable Cloud's own nginx.conf already defines, holding the scheme the request arrived with. The script ends with nginx -t, so a bad edit fails the build instead of the deployment.

We expected Cloud to write the config again when the container started, which would have thrown our change away. It does not. At runtime, Cloud's supervisor just runs nginx, and Nginx reads the file we left behind. The deployment succeeded on the first try, and /fast/ping came back from Go with X-Fastpath-Via: nginx.

The weakness is that this depends on who owns a directory in Cloud's build image. Nothing documents it. If Cloud tightens those permissions, or starts writing the config after the build, the script stops working. Our build command lets the script fail without failing the build, so as written, that change would quietly send /fast/ back to Laravel.

Option B uses Octane and FrankenPHP

This one also works, and we think it is the one to use.

With Octane on, Cloud starts the app with its own Caddyfile.

php artisan octane:start --server=frankenphp --host=0.0.0.0 \
    --admin-port=2019 --port=8080 --caddyfile=/Caddyfile ...

We cannot change /Caddyfile. But near the top of its route block, before the security rules and before php_server, it has a placeholder. This is a trimmed excerpt of what we found.

route {
    root "{$APP_PUBLIC_PATH}"
    # Mercure configuration is injected here...
    {$CADDY_SERVER_EXTRA_DIRECTIVES}
    ...
    php_server {
        index frankenphp-worker.php
        ...

Caddy fills {$...} placeholders from environment variables. Laravel Octane sets CADDY_SERVER_EXTRA_DIRECTIVES itself when it starts FrankenPHP, normally to configure Mercure, a real-time messaging hub. Since Octane 2.14, the caddy.env key in config/octane.php lets the app override the variables Octane passes to Caddy. The test app used Octane 2.24. So one setting puts our rule ahead of PHP.

'caddy' => [
    'env' => [
        'CADDY_SERVER_EXTRA_DIRECTIVES' => <<<'CADDY'
            reverse_proxy /fast/* 127.0.0.1:7070 {
                header_up X-Forwarded-For {header.X-Forwarded-For}
                header_up X-Forwarded-Proto {header.X-Forwarded-Proto}
                header_down X-Fastpath-Via caddy
            }
            CADDY,
    ],
],

The rest of the setup was ordinary Octane. We installed it with octane:install --server=frankenphp, committed public/frankenphp-worker.php, and turned Octane on for the environment.

Our first Octane deployment did not have the two header_up lines. The binary answered, but it was told the wrong things about the request, which the next section covers.

This option has three costs. It replaces Octane's Mercure injection, so an app that uses Mercure would have to put that configuration back in the same string. Requests to proxied paths skip the rules that come after the placeholder in Cloud's Caddyfile, including the ones that block .php files under /storage, dotfiles, and files with extensions like .sql and .sh. That matters only if the binary serves files. And it depends on Cloud keeping the placeholder where it is. That is still a better bet than Option A, because Octane's own Mercure support depends on the same placeholder.

What the binary saw

The binary always sees its connection coming from 127.0.0.1, because the web server in the same container is the one connecting to it. Everything else has to come from forwarded headers. We sent a probe request through each setup and read back what the binary reported.

Setup Client IP the binary saw Scheme the binary saw
Nginx, with the proxy_set_header lines our public IP https
Octane, without header_up the IPv6 address of Cloud's internal router http
Octane, with header_up our public IP https

Without the header_up lines, Caddy sets X-Forwarded-For and X-Forwarded-Proto from its own connection, which comes from Cloud's internal router over plain HTTP. With them, Caddy passes on the values the router sent. A binary that builds redirect URLs or rate-limits by IP would get both wrong without them.

How fast it was

We read Cloud's access logs for the Nginx version over ten minutes of requests. The access log's duration is the time the app spent on a request after it reached the container.

Route Requests Median
/fast/*, served by Go 32 0 ms
/php, a bare Laravel route on PHP-FPM 31 6 ms

The first /php request after the deployment took 181 ms. From the machine we tested with, both routes took about 200 ms to the first byte, because the app runs in Cloud's us-east-2 region and network time swamps a 6 ms difference. The access log is the useful comparison.

We did not measure Octane on Cloud the same way. In a local run, Octane served /php in 42 ms and the proxied /fast/ping in under 1 ms.

After the app slept

Cloud can hibernate an idle environment and wake it on the next request. Ours was set to hibernate after five minutes. We left the Octane version idle for about five and a half minutes and then requested /fast/ping. Go answered it, with the same process ID as before, in 439 ms. The next request took 233 ms, close to the usual figure.

That is consistent with the app waking up and the binary coming back with it. We cannot prove the app was asleep. Cloud's API reported the environment as running throughout, and it does not expose whether an instance is frozen. It is likely, not proven.

What we did not test

We did not put any load on either version. We did not try streaming responses, WebSockets, or large uploads through the proxy. We ran one replica, which is one copy of the app, so we do not know how this behaves when Cloud scales an app out to several. We built the binary in Go, but nothing here is specific to Go. A static Rust binary should work the same way.

Laravel does not support either approach. If you use one, put a test in your deployment that requests a proxied path and fails if the response did not come from the binary. That is the only way to find out the day Cloud changes something underneath it.

The idea behind this experiment

  1. Idea

    Can a Laravel Cloud app serve a few routes from a Go or Rust binary?

    A handful of routes in a Laravel app often do most of the work, and they are the ones we would rewrite in Go or Rust. Running them as a separate Cloud app means a second app, a second set of deploys, and a second bill. We want the binary inside the Laravel app, answering its routes before PHP or the framework is involved. Nothing has run yet.

    Read the idea

Support the Lab

The Lab runs on our supporters

Every idea here gets tried for real: deployed, broken, fixed and written up. Right now that is one person doing the work between everything else, and supporters are what buy the time. As support grows, it will also pay freelancers to run experiments of their own, so more of these ideas get tested, sooner.

Our supporters

  • Chill Vibes

    A curated collection of fun and interesting experiments and projects built with AI to entertain and educate.

    Supporter Visit
    Visit Chill Vibes
  • Fawnfox Fables

    Create and publish your own children's books. Stories built around the people you love.

    Supporter Visit
    Visit Fawnfox Fables
  • Sputnik Intelligence

    Spain

    We transcribe the podcasts and read the newsletters, and make them searchable. Set up alerts, or hand it all to your AI agent over MCP or API.

    Supporter Visit
    Visit Sputnik Intelligence
  • Team of Me

    Free resources for indie makers and people thinking about striking out on their own.

    Supporter Visit
    Visit Team of Me
  • Wicked Viral

    Earth

    Connecting builders with promoters who can help them take their products to market. Get your product listed today!

    Supporter Visit
    Visit Wicked Viral