Gpu Lan Runtime

gpu-lan-runtime

**Languages**: English | [简体中文 (README.zh-CN.md)](README.zh-CN.md)

**Turn any LAN machine with an NVIDIA GPU into a transparent remote CUDA runtime that any agent tool (Claude Code, Codex, OpenHands, WorkBuddy, Cursor, a CI pipeline…) can drive over SSH — synchronously, in seconds, fully autonomously.**

You run on a laptop / workstation **A** with little or no GPU. The compute sits on **B** across the LAN. This project gives **A** one local command that *feels* like a local `python …` but actually executes on **B**'s GPU:

python client/gpu.py python train.py --epochs 20

B may run **Windows or Linux** — the client auto-detects and drives both identically, and the two server script sets converge to the same secured end-state.

**Why not a message bus / the agent's own async channels?** Those need B to be running an always-on agent, poll for jobs, and answer in minutes. This project drives the **OS-level `sshd`** already present on B — a synchronous, seconds-latency request/response link that needs no resident agent on B at all.

---

Highlights

• One command = one remote GPU run. TCP probe → optional vRAM-queue wait → incremental SFTP code sync → run → stream stdout → pull runs/ back.
• Stable exit-code contract (0/1/2/3/4) so an agent never mistakes an environment failure for a code bug (and never edits correct code in a loop).
• Clean stdout. Only your program's output reaches stdout; every diagnostic goes to stderr. gpu.py … > results.txt is always clean.
• Cross-platform end to end — Windows and Linux on the B side (and A can itself be either); remote OS is auto-detected, per-call overridable.
• Hardened, key-only SSH. Provision scripts disable password auth, restrict the firewall to your LAN CIDR, use a non-admin account, and cap vRAM usage.
• Works with any agent that can run a shell command and read an exit code. No agent-specific plugin, no resident daemon on B.

---