Skip to content
Scalpels home

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

Guide

Patch NGINX and PHP on Forge with an agent

· Ed Grosvenor

Last updated

If you have several Forge servers and a security advisory open in another tab, start with one server. An agent can collect the facts, prepare the right update, and check the result. You do not need to give it SSH keys.

We used one temporary Forge API token and a read-only discovery recipe to find out what was actually installed. That revealed different NGINX package sources, PHP branches missing from Forge's inventory, and servers Forge could no longer reach. Those differences decide what to do next.

The workflow is to inspect with a recipe, review a plan, update PHP through Forge's PHP update action, update NGINX through a root recipe, and verify both. Forge still uses its existing connection to manage the server. The agent does not need its own SSH connection.

Ubuntu 20.04 or older needs a different plan. Those servers cannot get the NGINX fix through the package procedure in this guide. Create a new server on a supported Ubuntu release and migrate your applications. That migration is outside this guide. Do not ask the agent to force packages for a newer Ubuntu release onto the old one.

Check the current advisory first

Forge's NGINX2Root advisory describes the NGINX fixes released on November 18, 2026. It lists stable 1.30.7 and mainline 1.31.9 as the fixed releases. Check the branch as well as the number. Mainline 1.31.8 is not fixed just because its number is greater than stable 1.30.7.

Forge's November PHP security advisory lists PHP 8.2.36, 8.3.37, 8.4.28, and 8.5.13 as the fixed releases. A previous advisory's version list does not prove that a server has these fixes.

Packages arrive separately for each Ubuntu release. Forge's status notice at 17:43 UTC on November 19, 2026 confirmed packages for Ubuntu 26.04 only. Packages for Ubuntu 24.04 and 22.04 were not yet published, and Forge kept PHP updates disabled for those releases.

Before running an update, check your server's Ubuntu release against the advisory's current Patch status by Ubuntu version table and the latest status notice. During the approved update, refresh APT and have the agent confirm that the server's configured repository offers a fixed candidate. If it does not, record PHP as waiting for a patch rather than patched.

Ubuntu 20.04 and earlier will not receive these PHP fixes. Use the server migration guide instead.

PHP 8.1 and earlier have no fix for this advisory. Forge recommends moving sites to a supported PHP branch. A routine patch cannot make an unsupported branch safe. Plan and test that move separately, including the PHP versions used by command-line scripts, workers, and scheduled jobs.

Forge's automatic security updates do not take care of these NGINX and PHP packages for you. Updating NGINX also does not install the separate kernel fix mentioned in its advisory. Track that update and any required reboot separately.

Create one short-lived Forge token

In Forge, open your account dashboard, choose API, and click Create token. Give it a recognizable name, such as temporary-security-patching. Set the expiration date to tomorrow, or the shortest time that leaves you enough time to finish. Do not leave expiration blank.

Select these five scopes on the same token.

Scope Why the agent needs it
organization:view Find the organizations your account can access.
server:view List servers and Forge-managed PHP installations.
recipe:view Read recipes and their execution logs.
recipe:manage Create, run, and clean up recipes.
server:manage-php Ask Forge to patch an installed PHP branch.

Click Add token. You do not need an all-permissions token, SSH-key permissions, or site-command permissions. This workflow does not need server:manage-services because NGINX service actions happen inside the root recipe.

This is still a powerful credential. A token that can run a recipe as root can change the server. Calling a recipe read-only describes its script, not a restriction enforced by the token. Use an account with access only to the servers you intend to manage where practical.

Forge's token documentation covers creating and deleting tokens. Expiration is a backstop. Delete this token yourself when the work is finished, even if tomorrow has not arrived.

Give the token to the agent without putting it in chat

Use your agent's masked secret-entry dialog or secret manager. Never paste the token into a conversation, a prompt, a recipe, a screenshot, or a committed file. It belongs in the API client's environment, not on the server being patched.

In Amp, ask the agent to open a masked secret-entry dialog for a personal secret named FORGE_API_TOKEN. Enter the token there. Have the agent refresh its environment and confirm only that the variable is present. It should not print the value to prove it worked.

If your agent cannot offer private secret entry, stop and configure a supported secret store first. Do not fall back to chat. Ask it to keep authorization headers, tokens, and secret-bearing API error bodies out of logs too.

Start with a read-only discovery recipe

Give the agent a clear boundary before it connects. This prompt contains no credentials and is safe to copy.

Help me patch my Laravel Forge servers using the Forge API and recipes.
Do not use or create SSH keys. Read FORGE_API_TOKEN from the environment.
Do not display it or log authorization headers.

Start with discovery only.
- Read the current official Forge NGINX advisory and PHP release information.
- List accessible organizations and servers, following API pagination.
- Prepare a read-only root discovery recipe. Show me its complete script
  and intended server list before running it.
- Collect Ubuntu release, NGINX version, package revision and maintainer,
  NGINX and PHP package sources, cached APT candidates, holds, and modules.
- Collect every installed PHP branch, CLI and FPM package revisions,
  and service state. Compare this with Forge's PHP inventory.
- Do not read application files or secrets, refresh APT, change packages
  or repositories, restart services, or reboot during discovery.
- Avoid printing private repository credentials.

Report each server's findings and a proposed update and verification plan.
Flag unsupported Ubuntu, unreachable hosts, and unpublished patches.
Cached candidates may be stale. Inspect the per-server recipe logs.
An accepted run is not a completed run. Missing output is unverified.
Before retrying an ambiguous submission, check whether a run was created.

Wait for my approval before making any server changes.

In Forge Recipes, a recipe is a saved shell script that Forge can run on selected servers. This discovery recipe runs as root so it can inspect package and service information. Review the script before approving its execution. Root does not make a script read-only.

Useful checks include cat /etc/os-release, nginx -V, dpkg-query, apt-cache policy, and apt-mark showhold. Enumerating /etc/php and versioned PHP binaries helps find installations that the default php -v misses. Using php8.4 -n -v, for example, checks that binary without loading its PHP configuration. The agent should collect only the information needed for patching, not dump application configuration or complete APT source files into chat.

Do not skip servers you believe have no PHP. Forge only knows about installations it manages. In our discovery, host packages revealed additional CLI and FPM branches that were absent from Forge's list.

Read the result for each server. A run stuck at “running” with no output is not evidence that the server is reachable. Resolve it separately, or leave it explicitly unverified. Do not send an update recipe to a server you have not inspected.

Review the update plan

Before approving changes, take a provider snapshot or confirm a usable recovery backup. Save the current package versions and back up NGINX and APT configuration. Configuration backups alone are not a package rollback. Know how you would restore the server if it cannot start afterwards.

Expect a short interruption when services restart. Choose one server for the first update, check its sites, and then continue in small groups. If you have different NGINX package sources, test one server from each update path before applying that path more widely.

Keep the work limited to the affected packages. Do not turn an urgent security patch into a PHP branch upgrade, an operating-system upgrade, or an unrelated full-server upgrade.

Update PHP through Forge

For a branch Forge manages, use its built-in patch action. In the dashboard, open the server, then Runtime → PHP, open the branch's menu, and choose Update. This patches the installed branch. It is not the action for changing a site's PHP branch or the default CLI version.

The agent can request the same operation through the Update installed PHP version API, using server:manage-php. The current endpoint is PUT /orgs/{organization}/servers/{server}/php/versions/{phpVersion} under https://forge.laravel.com/api. The last value is the numeric PHP installation ID returned by Forge, not a string such as 8.4.

Apply the relevant fix to every supported installed branch, not just the default one. If discovery found a branch Forge does not list, do not assume this action covers it. For a supported branch, have the agent propose a separate root recipe based on the current PHP advisory. For PHP 8.1 or earlier, plan a move to a supported branch instead. Before removing any old PHP installation, check whether sites, command-line scripts, workers, or scheduled jobs still use it. Remove it only after those uses have moved or you have confirmed it is unused. Approve that work explicitly.

Wait for completion, then check the installed package revisions against the advisory. An API response accepting the request does not prove the update finished. An update that installs nothing because the mirror has not caught up is not a successful patch either.

Update NGINX with a root recipe

Have the agent prepare a separate recipe that runs as root, based on the current Forge advisory and the discovery results. Read its complete script and exact server list before approving a run.

There are two main paths.

  • NGINX already comes from nginx.org. Refresh APT during the approved update, confirm a fixed candidate for the configured branch, and upgrade NGINX while preserving the existing configuration.
  • NGINX comes from the old ondrej/nginx source. Follow Forge's repository migration procedure before installing the official package. The old PPA has been removed. Do not use add-apt-repository --remove for it. Preserve the separate PHP package sources.

Check the installed revision and maintainer, not just whether an nginx.org source is configured. We found servers with that repository configured but a Surý NGINX package still installed.

Repository migration can remove third-party NGINX modules, invalidate load_module directives, or add /etc/nginx/conf.d/default.conf. Have the agent stop and explain module dependencies or unexpected package removals instead of deleting configuration until the service starts. Check that your own default site still handles requests as intended.

A saved recipe is not an executed update. Run it on the approved first server, inspect its log, and verify the result before selecting more servers. The recipe must handle noninteractive package prompts deliberately, stop on errors, and avoid competing with another APT operation. Do not delete package-manager lock files to force it through.

Verify what is running

Ask the agent for a before-and-after result for each server, backed by recipe output and real site checks.

  • Check nginx -v and the installed package revision against the correct fixed branch. Run nginx -t and confirm the service is active.
  • Restart NGINX after the configuration test succeeds if the package operation did not already restart it. A reload does not load the patched binary. Verify the running master uses the installed executable, not an old replaced copy.
  • Check each affected PHP CLI and FPM version against the November advisory's fixed release for that branch, and record the full installed package revision. Backports from an older advisory do not establish that these fixes are present. PHP 8.1 and earlier remain unresolved until their uses have moved to a supported, patched branch and the old installation is removed.
  • Test FPM configuration and ensure the affected FPM services restarted successfully. Restart the application's long-running PHP processes, such as queue workers, Horizon, Octane, and Reverb, using the commands appropriate to that application. A blanket restart of every daemon is not necessary.
  • Make HTTP and HTTPS requests to the affected sites from outside the server. Check an application health endpoint or a representative page, expected redirects, and recent service and application errors. A listening port alone does not prove the site works.

Keep unsupported, unreachable, failed, and waiting-for-package servers separate from verified fixes. Do not let a successful recipe on one server stand in for the rest.

Clean up when you finish

Delete the temporary token from Forge → account dashboard → API → token menu → Delete. Do this even if you set it to expire tomorrow. Only delete the token created for this job, not a token an existing integration depends on.

Remove the stored token from your agent's secret manager as well. Revoking it in Forge does not delete the agent's copy. Clear any temporary environment injection through that tool's supported cleanup.

Keep a private record of the final package versions, checks, backups, and unresolved servers. Remove temporary recipes you no longer need after saving the useful evidence. Check that the update left no temporary service-restart suppression or package holds behind. Redact server identities and private output before sharing logs for help.

You are finished when the fixes are installed and running, the applications still work, and the temporary access is gone. An old Ubuntu server or a package that has not been published yet remains an open item, not a reason to guess.

Changelog

  1. Published.
  2. Added the November PHP fixes, Ubuntu package availability checks, and guidance for unsupported PHP branches.

Need help patching your Forge servers?

These agencies and freelancers are standing by and ready to help.

  • Scott Keck-Warren

    Michigan

    PHP and Laravel developer with 13 years of experience building and maintaining production apps. US Eastern, English.

    Freelancer Ask for help
    Ask Scott Keck-Warren for help
  • Artisan Build

    USA

    We run Scalpels, as well as a suite of other tools for developers and development teams.

    Agency Ask for help
    Ask Artisan Build for help