goway

goway lets you type a build or test command on your main laptop and have your other laptops do the work.

• It copies the files git shows for your project, including uncommitted changes, to the least busy helper laptop on your network.
• It runs the command there natively, with a warm build cache, at low priority, so the person using that laptop is not slowed down.
• It streams the output back and exits with the command's own result.

Helpers are found by name, not by fixed address, so laptops on changing Wi-Fi addresses keep working. A test run can also be split across several helpers. goway is built for Rust projects worked on from many git worktrees at once, and it runs any command. Every change goway makes to a machine is journaled, so uninstalling restores it exactly.

Install

goway runs on two kinds of computer: your main laptop, the one you type on, and one or more helper laptops, the ones that do the work. All of them must be on the same network.

Support at a glance. "Tested by the maintainer" means the maintainer ran it on a real machine; "untested by the maintainer (no such machine)" means it is built, or expected to work, but has not been run on real hardware.

Operating systems

Downloads. Every version's ready-made files are on the Releases page. These links always fetch the newest release (from v0.1.0):

Not sure which one? On Windows, Settings > System > About shows "System type" (x64 or ARM64). On Linux or a Mac, uname -m prints x86_64 or aarch64/arm64. The one-line installers below pick the right file for you.

# Linux or WSL
sha256sum --check --ignore-missing SHA256SUMS
# macOS
shasum -a 256 --check --ignore-missing SHA256SUMS
# Windows PowerShell: compare this with the line for the file in SHA256SUMS
(Get-FileHash .\goway-setup.exe -Algorithm SHA256).Hash

gh attestation verify goway-setup.exe --repo lognd/goway

On your main laptop, one command installs goway:

# Linux, or WSL on Windows
curl -fsSL https://github.com/lognd/goway/releases/latest/download/install.sh | bash

# Windows without WSL (download goway-setup.exe from the table above first)
.\goway-setup.exe install

# a Windows helper laptop with WSL (one command; it prints what to run next)
.\goway-setup.exe install --host

Other ways to install

From v0.1.0 goway is also on PyPI and crates.io, so uv, pipx, pip (in a virtual environment) and cargo can install it. Each is available from v0.1.0; the details, the PEP 668 explanation of why system pip is refused on Debian and Ubuntu, and where each puts the program are in docs/install-methods.md.

uv tool install goway          # available from v0.1.0 (preferred; install uv first: https://docs.astral.sh/uv/getting-started/installation/)
pipx install goway             # available from v0.1.0
cargo install --locked goway   # available from v0.1.0 (needs a Rust toolchain: https://rustup.rs)

After any of them, the next step is goway add. goway uninstall recognises the method and removes the program with the matching command (uv tool uninstall goway, pipx uninstall goway, cargo uninstall goway, or pip uninstall inside its virtual environment).

Each download is checked against the release's published checksums. The helpers do the building, so they need the toolchain for your project, such as Rust. goway add installs it for you. The main laptop needs only goway, git and ssh. Words you have not seen before are explained in docs/glossary.md.

Languages and test tools

Every row below except .NET has a sharding adapter (goway run --shard N, see docs/usage.md). The columns say what has been checked.

Sixty-second tour

goway add <YOUR-COMPUTER-NAME-HERE> ...     # once per helper: the line its installer printed
goway status                                 # are the helpers reachable, how busy are they?
goway run -- cargo nextest run --workspace   # run on the least busy helper
goway run --shard 2 -- cargo nextest run     # split one test run across two helpers
goway doctor --fix                           # check everything, fix what it can
goway uninstall                              # remove goway everywhere, exactly

Read top to bottom:

• status: each helper's current address and how goway found it, its processor type and cores, its load, and goway's jobs on it.
• run --shard 2: goway picks the two least busy helpers. It copies only what changed since the last run and gives each helper half of the tests (nextest's own --partition). Each output line is prefixed with the helper it came from.
• done / note: every goway line says its kind in words, and goway exits with the first failing shard's code, or 0.

Quick start: your first helper

1. On each helper laptop (once)

1. Download goway-setup.exe from the latest release.

2. Open the Start menu, type PowerShell, and open it. In the folder where the download went (usually cd ~\Downloads), type:

   .\goway-setup.exe install --host
   

3. Windows asks "Do you want to allow this app to make changes?". Choose Yes.

4. At the end, the installer prints one line starting with goway add. Copy that line or write it down; you need it in step 3.

2. On your main laptop (once)

Linux or WSL: open the terminal and type:

curl -fsSL https://github.com/lognd/goway/releases/latest/download/install.sh | bash

Then close the terminal and open it again.

Windows (without WSL): download goway-setup.exe from the same release and run .\goway-setup.exe install in PowerShell.

3. On your main laptop, once per helper

Type the line the helper's installer printed in step 1.4. It looks like this, with the helper's own values in place of the <...> parts:

goway add <YOUR-COMPUTER-NAME-HERE> --fingerprint <FINGERPRINT-FROM-THE-INSTALLER> --user <YOUR-LINUX-USER-NAME-HERE> --rsudo

goway shows what it is about to do, asks for the helper's Linux password once (not its Windows password), and finishes with goway: done: <YOUR-COMPUTER-NAME-HERE> is ready.

4. Try it

goway status                                  # are the helpers reachable?
cd ~/my-project                               # a folder kept in git
goway run -- cargo nextest run --workspace    # runs on the least busy helper

Everything after -- is the command the helper runs.

Install details for each operating system

Main laptop: Linux or WSL

curl -fsSL https://github.com/lognd/goway/releases/latest/download/install.sh | bash

This works on any Linux on Intel/AMD (x86_64) or ARM (aarch64), and inside WSL. It needs curl, git and ssh, which most systems have. If one is missing, goway add ... --lsudo installs it on Ubuntu or Debian. Remove goway again with goway uninstall.

Main laptop: Windows (without WSL)

1. Install Git for Windows (https://git-scm.com). Windows 10 and 11 already include the ssh client goway uses.

2. Download goway-setup.exe from the latest release. On a Windows-on-ARM laptop, take goway-setup-arm64.exe.

3. In PowerShell, in the download folder:

   .\goway-setup.exe install
   

4. Open a new PowerShell window and type goway --help.

Remove it in Settings > Apps > goway, or with goway-setup.exe uninstall. Details: docs/install-windows.md.

Main laptop: macOS

The release has goway binaries for Apple Silicon (aarch64-apple-darwin) and Intel (x86_64-apple-darwin). The same one-line installer as on Linux picks the right one, verifies it against SHA256SUMS with shasum -a 256, and installs it to ~/.local/bin:

curl -fsSL https://github.com/lognd/goway/releases/latest/download/install.sh | bash

The installer and goway uninstall use only what macOS ships (bash 3.2 and the BSD tools). The maintainer has no Mac: the binaries are built, and the client tests and installer scripts are run, on GitHub's macOS runners only. Without the release, build from source with Rust (https://rustup.rs):

cargo install --locked --git https://github.com/lognd/goway goway

A Mac cannot be a helper: goway's helper side needs Linux tools (GNU findutils, flock, setsid).

Helper: Windows with WSL

See step 1 of the quick start. The helper needs WSL 2 and Ubuntu. Windows 10 (21H2 or newer) and Windows 11 both work. With Windows 11 22H2 or newer, goway-setup uses WSL's mirrored networking. On Windows 10, or with WSL in NAT mode (networkingMode=nat), it instead sets up a Windows port relay (netsh interface portproxy) on the helper's port; a scheduled task re-points the relay whenever WSL's internal address changes. The firewall rules still limit who can connect, the goway add line is the same, and goway-setup uninstall --host removes the relay and the task. --network mirrored|nat|auto overrides the choice. Windows 10 and NAT mode are untested by the maintainer on real hardware. If WSL is missing, the installer stops and tells you how to add it.

Helper: Linux

There is no installer for Linux helpers yet. These steps are for Ubuntu or Debian; other distributions use their own package names.

1. On the helper, install the ssh server and goway's needs:

   sudo apt-get install -y openssh-server git tar util-linux findutils
   

2. Make sure your main laptop can reach it on port 22. Many desktop systems allow this by default; with the ufw firewall, run sudo ufw allow from <YOUR-LOCAL-NETWORK> to any port 22, for example 192.168.1.0/24.

3. Find its name with hostname, and its fingerprint with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.

4. On your main laptop:

   goway add <YOUR-COMPUTER-NAME-HERE> --port 22 --fingerprint <FINGERPRINT> --user <YOUR-LINUX-USER-NAME-HERE> --rsudo
   

goway finds Linux helpers as <name>.local when the helper runs the avahi-daemon service (Ubuntu desktop does). Otherwise, add --address <ITS-IP-OR-DNS-NAME>.

Day to day

• goway run -- COMMAND runs a command on the least busy helper; --host NAME picks one; --shard 2 splits a test run across two helpers.
• goway status shows how busy each helper is.
• goway doctor checks everything and says how to fix what is wrong.
• Press Ctrl-C to stop a run; goway stops it on the helper too.

Using a screen reader? Add --plain (or set GOWAY_PLAIN=1), and tables are printed as labelled lines such as host: <YOUR-COMPUTER-NAME-HERE>, load: 0.40, jobs: 0. Every goway line starts with its kind in words (error:, warning:, done:, next: ...), so color is never needed.

Old copies and caches on the helpers are cleaned up automatically (goway gc --dry-run shows what would go). More: docs/usage.md.

Uninstall

On your main laptop:

goway uninstall              # lists everything it will remove, then asks
goway uninstall --rsudo      # also undoes the administrator changes on helpers

Then, on each helper laptop, remove goway helper in Settings > Apps.

How install and uninstall work: the journal

Everything goway's installers and setup commands change is meant to be completely reversible. That is possible because goway keeps a journal: a written record of each change it makes, together with what was there before.

What goway does

More: config, how helpers are found, troubleshooting, glossary, goway versus other build systems, design, releases.

Why not Kubernetes or Docker?

They solve a different problem. Kubernetes and Docker run services and packaged images on machines set aside for them. goway runs one command from the folder you are working in on computers you already own and use, and then it is gone.

Something went wrong?

See docs/troubleshooting.md; if goway add says "Permission denied", start with its section "goway add says Permission denied" (no password set, password login off, a ban, and how to add goway's key by hand with goway add NAME --no-password). Every goway error ends with a next: line saying what to try, and goway doctor checks everything at once.

Development

git clone https://github.com/lognd/goway.git && cd goway
cargo nextest run --workspace                                # the test suite (Linux or WSL)
cargo clippy --workspace --all-targets -- -D warnings        # lints, warnings are errors
cargo clippy --target x86_64-pc-windows-gnu --workspace --all-targets -- -D warnings

The suite never touches a real remote machine: a fake ssh runs goway's remote side locally. The workspace has three crates:

• goway: the command-line tool
• goway-journal: the reversible change journal
• goway-setup: the Windows installer

The work itself is tracked with frob, a work-accounting tool: its tickets and evidence live in tickets/, and the changelog fragments live in changelog.d/.

Versioning and compatibility

goway follows Semantic Versioning. Before 1.0, a minor version may change flags, output layout or the config file; the config file rejects unknown keys, so a renamed setting is reported rather than ignored. The minimum supported Rust version is 1.98, pinned in rust-toolchain.toml and checked in CI. Releases are cut as described in docs/release.md.

Contributing

Contributions are welcome, from a typo fix to a new feature. Read CONTRIBUTING.md before opening a pull request; it covers the local setup, the gate, the commit format and the AI-assisted contributions policy. Everyone taking part is expected to follow the Code of Conduct.

Security

See SECURITY.md for how to report a vulnerability; please do not open a public issue for one.

License

MIT. See LICENSE.