cargo-offload

Offload Rust compilation to a remote server. Build on a powerful machine, get binaries back locally.

Prerequisites

Local: rsync, ssh, Rust toolchain
Remote: ssh server, Rust toolchain (via rustup)
Passwordless SSH access (SSH keys) to the remote server

Installation

cargo install --git https://github.com/patrickjeremic/offload

Or from a local clone:

cargo install --path .

Configuration

Set the remote host via CLI flag or environment variable:

# Environment variable (supports user@host:port format)
export [email protected]:22

# Or pass it every time
offload --host [email protected] build

Commands

build

Compile on the remote server and copy binaries back:

offload build
offload build --release
offload build --bin my-binary

Artifacts are placed in target/offload/<target>/<profile>/.

run / run-local

Build remotely, then run the binary locally:

offload run
offload run --bin my-binary
offload run --release -- --config app.toml

run-local is an alias for run.

run-remote

Build and execute on the remote server. Supports SSH port forwarding:

offload run-remote
offload -L 8080 run-remote
offload -L 3000:8080 run-remote -- --release

test

Run tests on the remote server:

offload test
offload test -- --lib

clippy

Run clippy on the remote server:

offload clippy
offload clippy -- -D warnings

toolchain

Manage toolchains on the remote server:

offload toolchain install nightly
offload toolchain list

clean

Remove remote build directory and local target/offload/:

offload clean

Global options

Flag	Short	Description
`--host <HOST>`	`-h`	SSH host (`user@host` or `user@host:port`)
`--port <PORT>`	`-p`	SSH port (default: 22)
`--target <TRIPLE>`		Target triple (default: `x86_64-unknown-linux-gnu`)
`--env <KEY=VALUE>`	`-e`	Environment variable for the remote cargo command (repeatable)
`--sync-git`		Include `.git/` in the sync (for builds that run `git`)
`--copy-all-artifacts`		Copy the full target directory including `deps/`, `build/`, `incremental/`
`--forward <SPEC>`	`-L`	SSH port forward: `port` or `local:remote` (repeatable)

Toolchain detection

offload picks up the project toolchain automatically:

rust-toolchain.toml ([toolchain] channel = "...")
rust-toolchain (plain text)
Local cargo --version as fallback

Override with +toolchain syntax:

offload +nightly build
offload +1.80.0 test

How it works

rsync syncs source to /tmp/cargo-offload/<project>/ on the remote
Toolchain and target are installed via rustup if needed
cargo <command> runs on the remote with the specified target
For build/run, compiled artifacts are copied back via rsync

Tips

Use SSH connection multiplexing for faster repeated connections:

# ~/.ssh/config
Host build-server
    ControlMaster auto
    ControlPath ~/.ssh/master-%r@%h:%p
    ControlPersist 10m

License

MIT

patrickjeremic/cargo-offload

README