Cache & Carry¶
EngFlow in a Box — Quick Start¶
A Bazel remote cache in a box. Plug it in, point Bazel at it, build faster.
Three steps get you building. Everything after them is optional — read a section when you want the thing it describes:
| Security and privacy | what leaves the box (almost nothing) and what it exposes |
| Good to know | the licence, the clock, sudo — the handful of things that surprise people |
| Troubleshooting | start here if ping fails |
| Everything else | networking, a friendlier name, the licence, the cache, building your own |
1. Plug in one cable¶
Run a USB-C data cable from your laptop to the Pi's USB-C port. That single cable does everything: it powers the box and carries your build traffic. The Pi 4 has only one USB-C port, so there is nothing to pick.
Your laptop sees a new wired network connection and configures itself automatically. Give it about a minute.
First boot takes a couple of minutes and reboots once; the connection drops and comes back.
Check it:
| Bash | |
|---|---|
10.55.0.1 is fixed — the box's own address on the USB-C link, the same on every
box and never handed out by DHCP, so it is safe to write into the ~/.bazelrc in
step 2. The address the box picks up on your network is your router's to assign
and can change; Using it from another machine
covers pinning that one with a DHCP reservation.
No power adapter is needed. If you'd rather use one — a laptop port that limits current, an unpowered hub in between, or you want the box to stay up when the laptop sleeps — see Powering it separately.
2. Point Bazel at it¶
Add these four lines to your user-level ~/.bazelrc:
| Text Only | |
|---|---|
Then build with the box:
| Bash | |
|---|---|
The first build fills the cache; the rest reuse it. bazel test --config=efcache
works the same way — test takes whatever build is configured with.
New to Bazel's remote cache? What build:efcache means. efcache is a name
you are making up here — any word would do. Flags written as build:<name> sit
inert in the file until you ask for them by name with --config=<name>, so adding
them changes nothing about the builds you run today. Everything else in this guide
assumes you did it this way; if you picked another word, use yours.
Why not plain build --remote_cache=...? Because that points every Bazel
build on the machine at the box, and when the box is in your bag those builds
fail rather than quietly going back to building locally: Bazel exits non-zero
on a cache it cannot reach (34) and on a results stream it cannot reach (38). We
measured both — the second one as far back as Bazel 7, the first from Bazel 8 on.
Opting in with one flag costs less than that.
~/.bazelrc, not the project's .bazelrc. The file in your home directory is
yours alone: it covers every project you build on this machine, belongs to no
repository, and Bazel reads it after the project's file, so your lines win over
whatever the repository sets. Put the same lines in the project's .bazelrc only if
the whole team shares the box.
10.55.0.1 is the box's address on the USB-C cable, so this works from the
machine the cable is plugged into with no network setup at all. To build from a
different machine, see Using it from another machine on your
network — same four flags, a
different address; to avoid an IP address altogether, see A friendlier name than
an IP address.
All four flags, not just the first.
--remote_cachealone gives you the speedup but leaves the UI empty:--bes_backendpopulates it, and--bes_results_urlmakes Bazel print a clickable link at the end of each build.
3. Watch your builds¶
Open http://10.55.0.1:8088 for the Build & Test UI: invocations, timing, and cache hit rates.
Bazel also prints a direct link to each build as it finishes, built from the
--bes_results_url you set above:
| Text Only | |
|---|---|
The UI is plain HTTP on port 8088 — no login, any browser, nothing to install.
What to expect¶
Measured on a real 1804-action open-source Bazel project:
| Build time | |
|---|---|
| Without the cache | 85 seconds |
| With Cache & Carry | 3.8 seconds |
That is a 22× speedup on a fully cached build. Use the USB-C cable, not Wi-Fi: the same build over this box's Wi-Fi takes 52 seconds.
Security and privacy¶
Short version: the box collects nothing from your machine, and sends nothing about your builds to EngFlow or to anyone else. It is safe to plug into your laptop and to put on your network.
No data about you or your builds leaves the box. Your source code, build artifacts, cache contents and build history are written to the SD card in the box and stay there. There is no analytics, no telemetry, no usage reporting, and no crash reporting — nothing in the software uploads anything about your builds anywhere. Your code never leaves your own machines and this box.
Only two things reach the internet, and neither carries your data:
| What | Where to | What it sends |
|---|---|---|
| The license check | my.engflow.com, at startup and on a five-minute re-check |
the box's own licence identifier — and nothing else |
| Clock sync (standard NTP) | the operating system's default time servers | nothing but a time request; this is stock Raspberry Pi OS behaviour, not ours |
The license request carries no build data: no file names, no source, no results, no timings, and no identifying information about your machine. Everything else the box does is local — Bazel talks to it directly over the cable or your network, and those requests never leave your network.
You do not have to take our word for it. Watch the box's traffic from your own network — your router's logs, or a capture on your own machine — and those two are all you will see. To watch from the box itself, install a capture tool first (it is not included) and filter out the USB link:
| Bash | |
|---|---|
It does not read anything from your computer. The connection is one-way in the sense that matters: your Bazel client decides what to send, and the box only ever stores what Bazel uploads to it. It has no access to your filesystem, mounts nothing, installs nothing on your machine, and runs no software there. Unplugging the cable leaves no trace beyond the network interface disappearing.
Plugging it in does not change your networking. The box gives your laptop an
address on a private point-to-point link (10.55.0.0/24) that reaches only the
box. It does not become your gateway, does not route your traffic, does not offer
DNS, and does not touch your normal connection — which keeps working exactly as
before, including your VPN.
What it does expose, so you can judge it. On whatever networks it is connected to, the box listens on three ports and none of them require authentication:
| Port | What it is |
|---|---|
| 8080 | the cache and build-event service Bazel talks to |
| 8088 | the Build & Test UI, in a browser |
| 22 | SSH, for the administrative commands in this guide |
Anyone who can reach those ports can read and write the cache and browse your build history. That is deliberate — it is what lets a team share one box — but it means:
- Keep it on a network you trust, and don't forward these ports through your router or otherwise expose the box to the public internet.
- Change the default password if it will be on a shared network: see one command.
- If you got this box at a conference, do that before you use it for real
work. It was set up to join the venue Wi-Fi by itself so that it would work
the moment you switched it on, and while it was on that network it was reachable
by everyone else there — with the same default password every other box had. We
think that is a fair trade for a demo box holding a throwaway cache of a public
example project, but it is your call to make knowingly rather than ours to skip
over. The two commands that settle it are changing the password and, if you
like,
sudo nmcli connection delete myEFbox-conference. - On the USB-C cable only, none of this is exposed to anyone — that link is point-to-point between the box and your laptop, with no path in from elsewhere. Leaving the box off your network entirely and using only the cable is the most private way to run it, and the fastest.
It is a demonstration appliance, not a hardened production server. The software
on it is the version we shipped, and nobody is patching it for you. That is fine for
the desk-side use it is built for; it is why we say keep it on a trusted network
rather than treating it as an internet-facing service. If you want to update the
operating system yourself, sudo apt-get update && sudo apt-get upgrade works
normally while the box is online.
To erase the cache and build history on a box you are keeping:
| Bash | |
|---|---|
To software-shred the SD card before passing the box on or repurposing it, shut it down, take the card out, and put it in a reader. Overwrite the whole device, not the files on it — one pass of zeros is enough, and more passes only wear the card:
- Windows —
diskpart, thenlist disk,select disk N,clean all, which sets "each and every sector on the disk" to zero: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clean - macOS —
diskutil listto find the card, thendiskutil secureErase 0 /dev/diskN; level 0 is a single-pass zero fill, andman diskutildocuments the rest. Apple's Disk Utility guide does the same job with a mouse, under Erase and then Security Options: https://support.apple.com/guide/disk-utility/erase-and-reformat-a-storage-device-dskutl14079/mac - Linux —
sudo shred -v -n 1 -z /dev/sdX: https://www.gnu.org/software/coreutils/manual/html_node/shred-invocation.html
Check the device name twice — all three erase whatever disk you point them at,
without asking. And one honest limit: SD cards do wear levelling, so the controller
can keep copies in spare blocks that no overwrite reaches; Apple's diskutil manual
and the GNU shred manual both say as much. This defeats file-recovery software,
which is what handing the box to a colleague needs. If the cache held something that
must not survive at all, destroy the card — a replacement costs a few dollars.
Good to know¶
It needs internet each time it starts. The box fetches its license from EngFlow every time it powers on, and it does not keep a copy — so it needs a network connection before your first build, and again after each power-cycle. Your builds themselves run entirely over the USB-C cable; only the licence check uses the internet.
In practice: plug it in, give it Ethernet or Wi-Fi (see Giving it internet — Ethernet needs no setup, and the Wi-Fi radio ships switched off), and it starts serving within a few minutes. Leave it powered and it stays licensed.
Given this box at a conference? It may already be set up for the venue's Wi-Fi, in which case there was nothing for you to do there — but that network is out of range once you're home, so you will need to give it one of your own. Giving it internet starts with how to tell.
If the UI shows an error page and the cache isn't responding, that is almost always
the licence. Connect Ethernet or Wi-Fi and give it about five minutes — the box
re-checks every five minutes and starts serving on its own once it can reach
EngFlow. If you'd rather not wait, power-cycle it (or run
sudo systemctl restart myengflow-mini over SSH) and it picks up immediately.
Nothing is damaged by being offline; the box simply waits.
Plugging it in won't break your internet. The box gives your laptop an address on a private link only. Your normal network keeps working.
Nothing about your builds is sent to EngFlow. No telemetry, no analytics, no source code, no build data — the box's only outbound connection is its own licence check. Full detail, including what it does expose on your network and why, is in Security and privacy.
Keep it on a network you trust. This is a demo appliance with default
credentials (myefbox / admin) and no firewall. Don't expose it to the public
internet. If it will live on a shared network, change the
password —
one command, and it becomes the new sudo password too.
If the cache fills up, your builds still work — see If the cache fills up for how to spot it and the one command that fixes it.
Its clock is set to UTC. That affects the box's own logs — docker logs,
journalctl — and it is deliberate: every box reads the same way wherever it ships,
so a log you send us never needs an offset worked out. The Build & Test UI is not
affected. It renders times in your browser's timezone, so it already shows your
local time and there is nothing to set. If you want the box's logs in local time too:
Either way this is display only — no bearing on your builds or on cache correctness.
Admin commands ask for the password. sudo on the box prompts for the same
admin password you log in with. Nothing about normal use needs sudo — Bazel,
the cache and the UI all just work — but administrative commands, like
joining a Wi-Fi network, will ask.
Troubleshooting¶
ping 10.55.0.1 fails. In order of likelihood:
- Charge-only cable. The most common cause — though not the cable that came in the box, which is a data cable. Many others carry power but no data wires, so the box powers up and lights its LED but never appears as a network connection. Swap in a known data cable.
- A hub or dongle in between. Some don't pass it through — plug the box straight in.
- No new interface. Check your network settings for a wired connection that
appeared when you plugged in (
ifconfigon macOS/Linux — look for an address like10.55.0.2). If none did, that's still symptom 1. - Still setting up. On the very first boot it reboots once; wait two minutes.
Green LED on but nothing else happens. Power reaches the box, so suspect the cable or a hub.
Bazel reports the cache is unreachable. Confirm the box is up:
| Bash | |
|---|---|
200 means healthy. The --http2-prior-knowledge flag is required — a plain
curl looks broken even when the box is fine.
Builds succeed but nothing is cached. First suspect a missing
--config=efcache — without it those lines are inert. Then check that nothing
overrides --remote_cache later — the command line beats every rc file — and look
for remote cache hit in Bazel's summary.
Builds work but got slow again, or Bazel warns RESOURCE_EXHAUSTED: Not enough
space to create a replica. The cache is full — a warning, not an error, and
your builds are still correct. Restart the box's stack and it accepts new data
again, losing nothing already cached:
| Bash | |
|---|---|
How to confirm it, and how to wipe the cache if it keeps happening, are in If the cache fills up.
The UI loads but shows no builds. It only lists builds sent to it: add
--bes_backend and --bes_results_url as in step 2. With only --remote_cache,
builds are cached but never reported.
Still stuck? Grab the logs and send them to your EngFlow contact:
| Bash | |
|---|---|
Everything else¶
The rest of the documentation is cache-carry-docs.md, next to this file. Nothing in it is needed to get a build running — read a section when you want the thing it describes:
| Giving it internet | Ethernet, Wi-Fi or a hotspot — it needs one to license itself |
| Using it from another machine | share one box across your team |
| A friendlier name | my.engflow.mini:8088 instead of an IP address |
| Renewing the license | usually nothing to do; here's what to check if the UI errors |
| Using your own cluster UUID | put the box on your EngFlow account instead of ours |
| Renaming it / changing the password | both optional, one command each |
| If the cache fills up | nothing breaks; one command fixes it |
| Other ways to power and connect it | power adapter, hub, Ethernet-only |
| Building your own box from scratch | for a colleague who wasn't given one |
© 2020–2026 EngFlow