Skip to main content

Run BB-Eco without internet access — air-gapped and Cyber Essentials deployments

BB-Eco is designed to work on machines and networks that have no path to the public internet. Two deployment patterns drive this:

  • Factory floors and OT networks that are physically or logically isolated from the corporate network
  • UK Cyber Essentials (and equivalent regimes) that require administrator accounts to have no direct internet access as a hardening measure

This guide covers both, with concrete step-by-step instructions for each.

What BB-Eco needs the internet for​

Two things, both optional:

  1. Downloading the BB-Eco installer from update.brainboxes.com
  2. Downloading firmware images from the Brainboxes manifest, used during firmware upgrades

Everything else — discovery, configuration, monitoring, applying templates, even firmware upgrades themselves — runs over your local network without ever talking to the internet.

The two scenarios below differ only in when the machine has internet access. Once the installer and firmware are on disk, BB-Eco is fully offline-capable.

Scenario A — Factory floor with no internet​

Story: an industrial control engineer needs to provision Brainboxes hardware on a production line. The factory network is air-gapped from corporate IT. The engineer's laptop has internet at the office, but not on the factory floor.

Steps​

  1. At the office (with internet):

    # Install BB-Eco from update.brainboxes.com — pick the right installer
    # for your OS from https://docs.brainboxes.com/get-started/bb-eco/install

    # Launch BB-Eco once. The first run downloads the firmware manifest
    # and (optionally) pre-caches firmware for every supported model.
    bb-eco upgrade --download-all

    The --download-all flag pulls every firmware image listed in the manifest into the local cache. It runs unprivileged — no sudo password prompt. Expect ~50 MB of downloads depending on how many models are in the catalogue.

  2. Verify the cache:

    bb-eco firmware status --json

    You should see cached: true next to every available firmware version.

  3. Travel to the factory floor. Bring the laptop. The cache lives in:

    OSCache path
    macOS~/Library/Application Support/bb-eco/firmware/
    Linux~/.config/bb-eco/firmware/
    Windows%APPDATA%\bb-eco\firmware\

  4. At the factory floor (no internet):

    • Plug into the factory network
    • Launch BB-Eco — discovery, configuration, and firmware upgrades all work using the cached firmware
    • The "firmware update available" badges in the dashboard reflect the cache as it was at your last office sync

  5. When you next have internet, re-run bb-eco upgrade --download-all to refresh the cache.

That's it. No special offline mode, no separate config — BB-Eco just uses what's on disk and never blocks waiting for the internet.

Scenario B — Cyber Essentials admin account​

Story: a UK government supplier needs to run BB-Eco from an administrator account on a Cyber Essentials-certified workstation. Cyber Essentials requires that "administrative accounts must not be used for general activities such as web browsing or email" — in practice this is implemented by removing internet access from admin accounts at the network or proxy layer.

The challenge: BB-Eco's firmware upgrades need administrator privileges (to bind UDP ports 67/69 for BOOTP/TFTP), but the admin account has no internet access to download firmware.

Solution​

Split the workflow between two accounts on the same machine, using the shared firmware cache:

  1. Sign in as a standard (non-admin) user with internet access.

  2. Run the manifest refresh and firmware download as that standard user:

    bb-eco upgrade --download-all

    This is intentionally an unprivileged operation in BB-Eco. The cache lives in the user's home directory; no admin rights needed.

    Why the cache is per-user, not system-wide

    BB-Eco deliberately keeps the firmware cache in each user's home directory rather than a shared system path. That means each user account that runs BB-Eco has its own cache. For Cyber Essentials, this is a problem — see the next step.

  3. Make the cache available to the admin account. A few options, in order of preference:

    • Symlink the admin account's cache directory at the standard user's cache. On macOS:

      # As admin
      ln -s "/Users/standarduser/Library/Application Support/bb-eco/firmware" \
            "/Users/admin/Library/Application Support/bb-eco/firmware"

      On Linux:

      # As admin
      ln -s "/home/standarduser/.config/bb-eco/firmware" \
            "/home/admin/.config/bb-eco/firmware"

    • Copy the cache directory between accounts. Simple but has to be repeated each time the standard user refreshes the cache.

    • Mount a shared partition at both accounts' cache paths. Cleanest in environments where you can't symlink between user homes for permission reasons.

  4. Sign out, sign in as the admin account. The admin account now has no internet access and a populated firmware cache. Launch BB-Eco — firmware upgrades succeed against the cached images, the manifest refresh fails silently (BB-Eco falls back to the cache), and the Cyber Essentials separation is preserved.

  5. Refresh cycle. When new firmware ships, sign back in as the standard user, run bb-eco upgrade --download-all, sign out, sign back in as admin. Quarterly or monthly is typical.

Cyber Essentials compliance note​

This pattern keeps the admin account fully offline at all times. Internet-dependent operations (manifest fetch, firmware download) only ever happen under the standard user account. The shared cache is the bridge.

If your Cyber Essentials interpretation prohibits even file-level sharing between standard and admin accounts, fall back to Scenario C below.

Scenario C — Fully air-gapped admin (USB sneakernet)​

The most restrictive deployment: the admin account runs on a machine that has never been connected to the internet, on a network that has never been connected to the internet. The standard-user-on-the-same-box trick from Scenario B isn't allowed.

Treat the firmware cache directory as a portable artefact:

  1. On any machine with internet access, install BB-Eco and run bb-eco upgrade --download-all.

  2. Copy the firmware cache directory onto a USB stick:

    # macOS / Linux
    cp -r ~/.config/bb-eco/firmware /Volumes/USB-STICK/bb-eco-firmware-cache

  3. Plug the USB stick into the air-gapped machine. Copy the directory into the admin account's cache path:

    # As the air-gapped admin
    cp -r /Volumes/USB-STICK/bb-eco-firmware-cache ~/.config/bb-eco/firmware

  4. BB-Eco on the air-gapped machine now has the same cache as the internet-connected one. Firmware upgrades work.

  5. Each time new firmware ships, repeat steps 1–3. Bring the USB stick back to the internet-connected machine for a refresh.

Engineering improvement on the roadmap

The USB sneakernet workflow currently relies on copying the cache directory verbatim. A first-class bb-eco firmware export-bundle command that emits a single signed .zip would be cleaner — track and harden the import side, support delta updates, etc. That's on the roadmap; until it lands, the directory copy is what's available.

Common gotchas​

  • First launch is the only time BB-Eco strictly needs the manifest. After the cache is populated, every subsequent launch can run with no internet. The "Update available" badges become snapshots of the manifest at last refresh.
  • Configuration templates are local files. They don't need internet access at all — export, edit, apply, and diff all run over your LAN.
  • The desktop app's "Check for updates" button in the Firmware tab tries the network first and falls back to the cache. The fallback is silent — you don't get an error, you just get the cached information.
  • Discovery doesn't need the internet. SSDP and mDNS are LAN-local. Devices appear in the dashboard as soon as they're on the same broadcast domain, regardless of whether your laptop has WAN connectivity.

More resources​

Tags:
Last updated on