XGS Image Builder
Nothing to install, and nothing kept

Build a bootable OPNsense image for a Sophos XGS

The official OPNsense image, with the os-xgs-npu coprocessor driver and plugin already laid into it. Choose how it should boot, and this page opens the build request for you.

  1. 1 Configure You are here. Nothing has started.
  2. 2 Start it From here with a token, or by filing an issue.
  3. 3 Download the image It is kept for seven days, then it expires.
Still being completed. The main part of the work is done. Some functions are being improved, and the XGS-specific integration is being completed where something is still missing - each gap is listed in the driver project - and it all arrives as updates, through its releases. An image built here installs the newest release.
This image has not been booted on any appliance. One image built here - 26.7, serial, 38400 baud - has been installed on an XGS 3300 (2026-10-16); no other combination has been booted on a device. Burn one and boot it before relying on it. The build runs on a GitHub runner, which has no Sophos hardware attached to it and never will.
You are reading the original repository's page. A build only runs for the account that owns the repository, so pressing Build it here files a request that this repository answers with a refusal - which the page will show you within seconds rather than leave you waiting. Two ways round it, and the first is one press: open Fork and build in my account below and give it a token, and it forks this repository for you and builds there. Or fork it yourself - the four steps, with pictures, are below - and use your fork's copy of this page. Either way it is your build, your artifact, your storage - the licence position, and CONTRIBUTING.md says why.

The image

what gets written to the disk

Downloaded from OPNsense's own mirror when the build runs, and its checksum verified against the release's own file. No part of an OPNsense image lives in this repository.

The console

the one choice that can lock you out

An XGS has no screen, so the serial port is the only way in. Get this wrong and the appliance boots perfectly into a console you cannot read. Neither value is safer in the abstract - match whatever your terminal is set to.

On an appliance with no video output the two behave the same. Leave it on serial only unless you have a reason.

The rack models, such as the XGS 3300, have an LCD and keys on the front; the desktop ones, such as the XGS 136, do not. Yes adds the front panel plugin and LCDproc to the image.

The driver

fetched at build time, not stored here

Leave this as latest - the project's newest release, the one an appliance's Updates page offers - unless you know why not; main is everything merged, released or not. The source is placed in the image; a built module is not, because a module has to be compiled against the kernel the appliance is actually running.

Builds on GitHub

as they run, from this repository's Actions

    Reading the builds...

    Your own copy, step by step

    four steps, once - then this page is yours

    A build runs in the account that owns the repository, so your image is built in your own copy of it: your Actions minutes, your artifact, nothing kept by anyone else. The copy brings this page with it, and from your copy it files and builds in your account. If you would rather not do it by hand, Fork and build in my account above does all of it with a token.

    1. Fork the repository

      Open xgs-image-builder on GitHub, signed in, and press Fork at the top right.

      The repository's header on GitHub with the Fork button framed

    2. Create the fork

      Leave the name as it is - xgs-image-builder - with Copy the main branch only ticked, and press Create fork.

      GitHub's Create a new fork form with Create fork framed; the account's name is blurred

    3. Turn on its workflows

      GitHub turns workflows off on a new fork. In the fork, open Actions and press I understand my workflows, go ahead and enable them.

      The fork's Actions tab saying workflows are not run on it, with the button that enables them framed

    4. Publish its page

      In the fork, open Settings, then Pages: under Build and deployment, choose the branch main and the folder /docs, and press Save. A minute later your page is at https://your-account.github.io/xgs-image-builder/ - this page, building in your account.

      The fork's Pages settings: deploy from the branch main, the folder /docs, and Save framed

    Installing the image

    Never done it before? Installing, step by step shows every step below with a picture - the USB stick, the console, the installer and the first sign-in.

    1. Unpack it. The download is a zip holding one .img.xz. Unzip it, then decompress the .xz - 7-Zip on Windows, xz -d elsewhere - to get the .img.
    2. Write it to a USB stick of 4 GB or more with a raw image writer - Rufus in DD mode, balenaEtcher, or dd. Everything on the stick is replaced.
    3. Connect the serial console at the speed chosen on this page - 115200 or 38400 - 8 data bits, no parity, 1 stop bit, no flow control. An image built before 2026-10-16 at 38400 prints its login prompt at 115200; build it again.
    4. Boot from the stick: put it in a USB port, power on, and choose it in the boot menu or put it first in the boot order.
    5. The first boot runs from the stick and installs the driver and the plugins into the running system (the log is /usr/local/share/xgs-image/firstboot.log). Wait for the login prompt. The front ports are not there yet: the driver is loaded from the next boot on.
    6. Install to the appliance's disk: log in as installer with the password opnsense and follow the installer. The disk chosen is erased - on an XGS the internal disk holds the vendor's firmware. When it finishes, take the stick out and reboot.
    7. The first boot from the disk counts thirty seconds down on the console: "XGS: assigning the front ports by the names on the chassis". Let it run out and the ports are assigned by the names printed on the chassis; press any key to assign them by hand from the console menu. Automatically:
      • WAN: Port2 on an XGS 3300, Port1 on an XGS 136 - by DHCP;
      • LAN: every other front port, an expansion module's included, in one bridge on 192.168.1.1/24 with DHCP;
      • MGMT: the management port, where there is one (the XGS 3300's), on 192.168.100.1/24 with DHCP.
    8. Connect: https://192.168.1.1 from any LAN port, or https://192.168.100.1 from the management port, and log in as root / opnsense - then change that password. The management port you installed through answers on 192.168.100.1 from this boot on, not on 192.168.1.1.
    9. Updates: the driver from System - Firmware - XGS Coprocessor XGS Coprocessor - Updates XGS - Updates, which offers its releases; the translation, the layout and the plugins follow their own releases by themselves, once a day.