← NUILab Software

Docs / Get started / Overview

Get started

Overview

What offload is, how to install it, and the everyday commands.

offload 0.1.0

Do the heavy work on another machine when you are on a metered link.

A laptop on a phone hotspot pays for every byte. offload moves the work to a machine with a normal connection, reached over ssh, and sends only small, compressed results across the metered link.

It has two parts:

  1. offload redirect sends Claude Code’s API traffic through another machine. Each request crosses the link as the difference from earlier requests.
  2. offload claude, run, put, get, fetch run the work on the other machine and copy only the files that changed.

One Python file. No dependencies beyond Python 3.8+, ssh and rsync. MIT license.

Why the redirect saves data

Every Claude Code API call resends the whole conversation: the system prompt, the tool definitions, every file, screenshot and image already in context. Prompt caching lowers the bill, not the bytes sent. A long job with images can upload gigabytes.

Setting ANTHROPIC_BASE_URL to a plain proxy does not help, because the same bytes still cross the link. offload redirect runs a small relay at each end:

Claude Code ──► relay on the laptop ══ ssh over the metered link ══► relay on the box ──► api.anthropic.com
             (127.0.0.1:8484)          only what is new                (full request rebuilt)

The laptop relay cuts each request into chunks at JSON block boundaries. Both relays remember the chunks they have seen. A new request is sent as “the same chunks as request N, plus these new ones”, compressed. The relay on the box rebuilds the exact bytes, checks them against a hash, and forwards the request to the API with the original headers. Replies stream back as they arrive.

In a short test session, later requests went from about 170 KB each to 1–4 KB each. The first request of a session is sent in full (compressed), and new content, such as a new image, crosses once.

Install

Install on the laptop and on the machine that will do the work (“the box”):

git clone https://git.nuilab.org/f.ortega/offload.git
sh offload/install.sh            # copies offload to ~/.local/bin

The laptop must reach the box with ssh <box> without a password prompt (keys or an agent).

Redirect Claude Code’s API traffic

offload redirect mybox        # turn it on, through the machine "mybox"
offload redirect status       # is it on, and how much it saved
offload redirect off          # turn it off

redirect <box> starts a background relay (a launchd agent on macOS, a systemd user service on Linux) and sets env.ANTHROPIC_BASE_URL in ~/.claude/settings.json. Claude Code sessions started after that use the relay. Sessions that are already running keep their old setting until restarted. redirect off removes the setting and stops the relay.

Add --no-settings to leave settings.json alone. Then set ANTHROPIC_BASE_URL=http://127.0.0.1:8484 yourself for the sessions that should use the relay.

Things to know:

  • Only API calls are redirected. Tools still run on the laptop. A web page that Claude Code fetches locally still crosses the link. To move everything, use offload claude.
  • If the box is unreachable, calls go directly to the API so Claude Code keeps working. offload redirect status shows how many bytes went direct.
  • Your login token travels in the request headers through both relays. The laptop relay listens on 127.0.0.1 only. The relay on the box listens on a private unix socket that only your user can open, reached through ssh. Neither relay logs or stores headers. Request bodies are held in memory on the box while the relay runs, and never written to disk.
  • The relay on the box needs no setup. ssh starts it when the laptop connects, and it exits when the laptop disconnects.

Work on the other machine

Set a default box once, or pass -b <box> on any command:

offload box mybox
CommandWhat it doesWhat crosses the link
offload claude [dir]Copies dir to the box and starts Claude Code therethe files once, then terminal traffic
offload run <cmd...>Copies this folder, runs the command on the box, brings changed files backchanged files only
offload put <path>Sends a file or folderchanged parts, compressed
offload get <path>Brings a file or folder backchanged parts, compressed
offload fetch <url>The box downloads the URL and keeps the filealmost nothing

Paths map by home directory: ~/work/x on the laptop is ~/work/x on the box. A path outside your home directory lands under ~/offload/ on the box.

Each command prints how many bytes crossed the link. Before a first copy larger than 50 MB, offload asks; pass -y to skip the question.

A .offloadignore file in a folder lists rsync exclude patterns for that folder, one per line (for example node_modules/).

Compression helps text (code, logs, CSV, JSON). Images, video, PDF and Office files are already compressed, so the saving there comes from sending only what changed.

Run offload on other hosts

offload -H laptop redirect mybox      # turn the redirect on, on the host "laptop"
offload -H a,b,c version              # run a command on several hosts

-H comes first and takes one host or a comma-separated list. The command runs there over ssh.

Configuration

~/.config/offload/config.json, all keys optional:

KeyDefaultMeaning
boxnonedefault machine that does the work
port8484local port of the laptop relay
upstreamhttps://api.anthropic.comwhere the box sends API calls
remote_cmdoffload found on a PATH with ~/scripts, ~/.local/bin, ~/bin addedhow to start offload on the other machine
claude_launchtmux new-session -A -s {name} -c {dir} claudecommand offload claude runs on the box
confirm_mb50ask before copying more than this

State and logs are in ~/.local/state/offload/. The redirect log lists each request with its size before and after, and never contains headers or bodies.

Limits

  • The dedup works on request bodies. Replies are compressed, not deduplicated; they are small next to requests.
  • After Claude Code compacts a conversation, the next request is mostly new and crosses in full once.
  • offload run brings back files that are newer on the box. It does not delete local files that the command deleted on the box.
  • Tested with Claude Code on macOS and Linux. Other tools that honor ANTHROPIC_BASE_URL should work but are untested.

License

MIT. See LICENSE (opens in new tab) .

Source: README.md in offload, the same file that ships with the code.