box64 ranks the command line below two configuration files, and DynaCache can write up to 2Gb by default

The settings priority puts the command line last

Most tools resolve configuration so that the command line wins, because it is the most specific place a value can come from. Box64 states the opposite order.

The precedence is written as a single line: `~/.box64rc` first, then `/etc/box64.box64rc`, then the command line. Both configuration files are INI format, and both are real paths on the filesystem, with the system one under `/etc`.

So a flag typed on the command line loses to a per-user file, and both lose to nothing but the per-user file. The only way a command line option takes effect is if neither rc file sets that variable.

The file explains what to do about it, and the instruction is the opposite of removing the file. If you do not want to use the default `/etc/box64.box64rc`, copy it to `~/.box64rc` to ensure compatibility. So the recommended response to a system-wide configuration is to duplicate it into your home directory, which then takes precedence over it and over anything you type.

That is a defensible design for an emulator whose correctness depends on consistent settings across every invocation on the machine, and an inconvenience for anyone scripting it. A wrapper that passes flags will find its flags ignored on any system with a packaged configuration file.

The translation cache writes to the home directory and grows to 2Gb

The emulator translates code at runtime, and it keeps what it translates.

The note says DynaCache is now enabled by default, with compression. It creates files in `~/.cache/box64` to save the generated code for executed binaries and libraries, so launch time is greatly reduced on a second run. The files are compressed and will take up to 2Gb by default.

So the default state of a fresh installation includes a cache directory in the user's home that grows until it reaches a two gigabyte ceiling. That is a consequence of the performance claim rather than an accident: the emulator is described as running five to ten times faster with its dynamic recompiler than with the interpreter alone, and the cache is where the recompiled output survives between runs.

Turning off the writing is done through the same rc file mechanism, and the switch has three states rather than two. Writing the variable into `~/.box64rc` puts the cache into a read-only mode:

[*]
BOX64_DYNACACHE=2

or 0 to disable it completely. The section header is `[*]`, an INI wildcard that applies the setting to every program rather than to one named entry.

Read-only mode is the useful middle setting: it keeps the speed-up from an existing cache while stopping new writes, which matters on a device with limited storage.

One documentation link has a percent-encoded en dash in its path

Among the links in the introduction there is one with unusual characters in its path.

The link text is about a deeper look at the dynamic recompiler, and its target contains the sequence `%e2%80%91` twice inside the path, in place of what should be hyphens. Those bytes are the percent-encoded UTF-8 form of a non-breaking hyphen (U+2011). It appears in the fragment describing a high-level view followed by a low-level view.

The path is otherwise a plain site URL.

The other links in that block point to the website, the changelog, the game compatibility list, the performance analysis, and a paper reference with a DOI.

The file has other editing traces in the cache note, such as "This will creates" and "to completely disabled it".

box64 -k kills every emulated process on the machine

The usage section is four lines and the second one is a kill switch.

box64 ./program [args]
box64 -k
box64-bash

The first runs a program. The second is described as killing all the emulated processes.

The third line gives an x86-64 bash environment, which is the shell you use once you are inside the translated world rather than on the host.

There is a fourth path that is not a command but a caveat. Some shell scripts, the GOG game installer named as an example, check the reported machine architecture with `uname -m` and take a different path when they do not get x86-64. The fix given is to run such a script through the emulator explicitly, as `box64 script.sh`, so the emulator can take over that call.

That is the general shape of the problem: the emulator translates function calls, not what a program believes about the system it is on.

The documented OpenGL workaround is to override the version the driver reports

There is a section on Unity games and it recommends lying to the driver.

The first point is that many Unity games require OpenGL 3 or newer, which may be challenging on single-board computers built on ARM or RISC-V. The tip for Raspberry Pi 4 and 5 owners is to set `MESA_GL_VERSION_OVERRIDE=3.2` together with `BOX64_DYNAREC_STRONGMEM=1`, in order to prevent freezes and to enable strong memory mode.

So the environment tells the graphics driver to report a higher OpenGL version than it actually supports, which is what makes the game attempt to start at all. The second variable in the same line is a different kind of setting, which the README says enables strong memory mode.

A second workaround follows for ARM boards using the Panfrost driver: enable `PAN_MESA_DEBUG=gl3` to force higher OpenGL profiles, with the stated use case being a game that starts and then quits before showing anything.

Both are compatibility shims applied from outside the program, and both leave the underlying mismatch in place. A title that needs an OpenGL 3.2 feature the hardware does not implement will get further with the override and then fail on the feature, rather than fail early on the version check.

Steam and Wine each have their own document.

The tree holds Android and 32-bit targets the README does not discuss

The repository root is a good deal larger than the documentation suggests.

Alongside the obvious directories for the source, tests, documentation and build files there are four directories whose names describe host and binary combinations: `x64android`, `x86android`, `x64lib` and `x86lib`. None of those directories appears in the README's platform discussion.

There is also a `tests32` directory beside the main `tests` directory, two wrapper regeneration scripts where one handles the 64-bit case and the other the 32-bit one, and a `gdbjit` directory for integrating with the debugger's just-in-time interface.

The 32-bit story in the documentation is a redirect rather than a feature. The platform notes say 64-bit libraries are required on the host because the emulator translates x86-64 function calls directly, and that 32-bit binaries should be run with Box86 or Box32. Box32 is described as still experimental, though fairly stable now and usable. Wine gets the same treatment: Wine64 and Proton are supported, 32-bit components need Box86, and a Wine WOW64 build can run x86 Windows programs in a Box64-only environment, which is also called experimental but said to work in most cases.

The acknowledgements list advertising as a way to contribute

The closing section is a list of names, and one of its categories is not a contribution of code or money.

The opening line says there are many ways to contribute and names four: code, financial, hardware and advertisement. The list that follows is organised by exactly those categories.

Four individuals are credited for major code contribution. Eight entities are credited for major financial contribution, among them Playtron, CubeCoders Limited and the libre-computer-project. Hardware contribution has its own heading, and it is split again: two entries for hardware contribution and the LoongArch migration, then ten entries for hardware contribution alone, which is a list of boards, modules and vendors.

The last category is for the continuous advertisements for the project, and it names five channels or teams, four of them YouTube channels and one a site.

Putting advertising in the same list as code and hardware is unusual, and it is a reasonable reading that the emulator reaches its audience through small independent channels rather than through a marketing department. It also means the README carries outbound links to five promotional channels as part of its thanks.

The section ends with a request rather than a summary: if you use Box64 in your project, please mention it. Above it, the same file credits the logo and icon to one person, and offers the project a Chinese and a Ukrainian README alongside the English one.

Editorial conclusion

box64 fits a case where you want to run a specific x86-64 binary on an ARM board without building it from source, and it is a poor fit as a transparent layer, because it rewrites what the program believes about the machine. Three things to know before you rely on it. Configuration precedence is inverted from what most tools do: a command line option is overridden by a system-wide file, so a flag you typed can be silently replaced by a package's configuration. The translation cache is on by default, writes into the home directory, is allowed to reach two gigabytes, and is only made read-only by editing a file. And the documented workaround for OpenGL problems is to override the version string the driver reports, which moves the failure rather than removing it. Read the usage documentation before putting it in front of users.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ptitSeb/box64 on GitHub
4. README
5. Releases