Prerequisites

What the machine must already have before Install
will work, and how much of it to buy.

Who this is for. Whoever is choosing or preparing the host.

Before you start. BenchPress installs into an existing Frappe bench and
drives that host's Docker. It is not a standalone service, and it is Linux
only — the setup script uses apt and sysctl.

Steps

1. Confirm the platform is supported. See the table under
   Supported platforms.

2. Confirm the versions. See Versions. The host bench must be
   Frappe v16.

3. Give the bench user the Docker socket. BenchPress creates containers,
   networks and volumes as itself.

   sudo usermod -aG docker "$USER"
   newgrp docker
   docker info >/dev/null && echo "socket ok"
   

   setup.sh does this for you. It is listed here because the group change
   only takes effect on a new login, and a bench started before that cannot
   reach Docker.

4. Turn on IP forwarding. Traffic from a laptop on the tunnel reaches a
   bench container through the host, and the kernel drops it without this.

   echo "net.ipv4.ip_forward = 1" | sudo tee /etc/sysctl.d/99-benchpress.conf
   sudo sysctl --system
   sysctl net.ipv4.ip_forward        # net.ipv4.ip_forward = 1
   

5. Install a container runtime that gives a bench its own kernel view.
   BenchPress deploys with sysbox-runc by default, so a lab user gets root
   inside the bench without holding root on the host.

   docker info --format '{{.Runtimes}}' | grep -q sysbox && echo "sysbox ok"
   

   If sysbox-runc is not registered, either install it or change
   default_bench_runtime — and then read
   Production safety before you do,
   because runc without userns-remap makes in-container root host root.

6. Raise the kernel ceilings if you plan to run many benches. They are
   host-wide, and the machine image chose them, not you.

   sudo scripts/tune-host.sh --benches 1000
   

   The script lives in the benchpress_devops checkout, not in the app. Run
   it from there. It writes one drop-in under /etc/sysctl.d/, applies it,
   and re-reads /proc/sys to prove the raise took. Skip it on a small host
   and let Diagnostics tell you when it matters.

7. Open the WireGuard port.

   sudo ufw allow 44556/udp
   

Verify

Run all four. Every one must answer before you install.

docker info >/dev/null && echo "docker ok"
sysctl -n net.ipv4.ip_forward                 # 1
docker info --format '{{.Runtimes}}'          # includes sysbox-runc
bench version                                 # frappe 16.x

Supported platforms

The table is about the host that runs BenchPress. A browser on any
operating system can reach a deployed bench over the tunnel.

Versions

A bench you deploy can target a different Frappe version than the host. A Lab
accepts version-16, version-15, version-14 and develop. develop
tracks Frappe nightly and is unstable by definition.

Sizing

The CPU floor was measured, not guessed. The benchmark ran on 2026-07-02 on a
two-vCPU KVM guest with an AMD EPYC 9355P host CPU and 7.8 GiB of RAM, on
Frappe 16.25.0. Docker's --cpus limit was applied to benchpress_backend
only — the service that runs migrations, authentication and API requests.
Database, Redis, nginx, websocket, scheduler and worker containers were not
capped, so these numbers describe the backend allocation, not a whole-host
limit.

Three criteria, each with its own minimum:

Concurrent reads at each candidate cap, 30 authenticated requests per endpoint
at 10-way concurrency:

The enforced baseline is one CPU core. The measured tier maximum is 0.5,
but Lab.cpu_cores is an integer field, so a fractional allocation cannot be
stored. One core is the smallest representable value at or above the measured
minimum.

Read that as a schema floor, not a performance claim. The 0.5-CPU candidate
did not visibly degrade this workload, so the measurements do not support
calling one core a minimum. Re-run the benchmark after the application grows,
or when you change the host class.

RAM and disk are the real constraints, not CPU. A lab image is 5.5 GB to
19.7 GB, and one deploy costs roughly 0.2 GB to 1 GB more. See
The image cache for what that grows into and how
the sweep holds it down.

Troubleshooting

Reference

Related

• Install — the next page, once every check above passes.
• Production safety — what this host is and is not ready for.
• Diagnostics — the same checks, run by the app against the live host.