Skip to content

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
ping -c 3 10.55.0.1

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
1
2
3
4
build:efcache --remote_cache=grpc://10.55.0.1:8080
build:efcache --bes_backend=grpc://10.55.0.1:8080
build:efcache --bes_results_url=http://10.55.0.1:8088/invocation/
build:efcache --remote_timeout=600

Then build with the box:

Bash
bazel build --config=efcache //...

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_cache alone gives you the speedup but leaves the UI empty: --bes_backend populates it, and --bes_results_url makes 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
INFO: Streaming build results to: http://10.55.0.1:8088/invocation/<id>

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
1
2
3
ssh myefbox@10.55.0.1                    # password: admin
sudo apt-get install -y tcpdump          # needs the box to be online
sudo tcpdump -n -i any 'not net 10.55.0.0/24 and not port 22'

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
1
2
3
4
ssh myefbox@10.55.0.1                    # password: admin
sudo systemctl stop myengflow-mini
sudo rm -rf ~/.cache/myengflow_mini/cas
sudo systemctl start myengflow-mini

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:

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:

Bash
ssh myefbox@10.55.0.1                    # password: admin
sudo timedatectl set-timezone America/New_York

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:

  1. 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.
  2. A hub or dongle in between. Some don't pass it through — plug the box straight in.
  3. No new interface. Check your network settings for a wired connection that appeared when you plugged in (ifconfig on macOS/Linux — look for an address like 10.55.0.2). If none did, that's still symptom 1.
  4. 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
curl -s -o /dev/null -w '%{http_code}\n' --http2-prior-knowledge \
    http://10.55.0.1:8080/healthz

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
ssh myefbox@10.55.0.1 'cd ~/myengflow && docker compose restart'

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
ssh myefbox@10.55.0.1 'docker logs --tail 200 engflow-cache'

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