Docs / Get started / Overview
Get started
Overview
What offload is, how to install it, and the everyday commands.
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:
offload redirectsends Claude Code’s API traffic through another machine. Each request crosses the link as the difference from earlier requests.offload claude,run,put,get,fetchrun 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 statusshows how many bytes went direct. - Your login token travels in the request headers through both relays. The laptop relay listens on
127.0.0.1only. 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
| Command | What it does | What crosses the link |
|---|---|---|
offload claude [dir] | Copies dir to the box and starts Claude Code there | the files once, then terminal traffic |
offload run <cmd...> | Copies this folder, runs the command on the box, brings changed files back | changed files only |
offload put <path> | Sends a file or folder | changed parts, compressed |
offload get <path> | Brings a file or folder back | changed parts, compressed |
offload fetch <url> | The box downloads the URL and keeps the file | almost 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:
| Key | Default | Meaning |
|---|---|---|
box | none | default machine that does the work |
port | 8484 | local port of the laptop relay |
upstream | https://api.anthropic.com | where the box sends API calls |
remote_cmd | offload found on a PATH with ~/scripts, ~/.local/bin, ~/bin added | how to start offload on the other machine |
claude_launch | tmux new-session -A -s {name} -c {dir} claude | command offload claude runs on the box |
confirm_mb | 50 | ask 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 runbrings 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_URLshould 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.