recom

Write code locally. Compute remotely. Generated outputs sync locally.

Supports 17+ languages

---

Write code in your macbook air, run the heavy compute on your Linux workstation seamlessly. The output files are automatically sent to your macbook air.

# instead of
python3 heavy_cuda.py

# run
recom python3 heavy_cuda.py

# instead of
g++ heavy_sim.cpp -o heavy_sim
./heavy_sim

# run
recom g++ heavy_sim.cpp -o heavy_sim
recom ./heavy_sim

No laggy remote editor, no setting up network filesystems, no daemon, no remote virtualenv to manage by hand.

Table of Contents

• Install
• Quick Start
• Dependencies
• What a run does
• Long Jobs
• More Information
• Development
• License

Install

You only have to install recom on your local machine. No install is needed on the remote compute workstation.

recom currently only supports MacOS and Linux for local, and Linux for compute backend.

Requirements

• Local: OpenSSH, rsync 3.x (on macOS: brew install rsync)
• Backend: A Linux machine, sshd, rsync, tmux(optional), language runtimes (uv is recommended for Python)

Install Script (Recommended)

• Install

curl -fsSL https://raw.githubusercontent.com/chaseungjoon/recom/main/install.sh | sh

The script above installs recom to ~/.local/bin.

• Update

recom update

Releases tab

Download the archive for your platform from Releases, verify it, and put recom on your PATH:

Build from source

Requires Golang (see go.mod) and make:

git clone https://github.com/chaseungjoon/recom.git && cd recom
make build                      # bin/recom, with the Linux helpers embedded
mkdir -p ~/.local/bin && install -m 0755 bin/recom ~/.local/bin/

Use make build, not plain go build: the client embeds the cross-compiled Linux helpers it installs on backends.

Quick start

# 1) Setup remote compute backend
recom ssh <username>@<host>

# 2) Initialize recom
cd ~/Projects/my-model
recom init                     # creates .recom.toml (commit it) and sets up the backend environment

# 3) Run any script with 'recom' prefix
recom python3 src/run.py
recom nvidia-smi               # anything: gcc, make, pytest, nvcc, ...

outputs land at the matching local paths.

Dependencies

Declare dependencies the way you already do, once, on your laptop.

recom installs them on the backend automatically and keeps them in sync:

You have	recom does on the backend	Your commands get
requirements.txt, pyproject.toml, uv.lock, poetry.lock, Pipfile	builds .venv (with uv when available)	python3, pip, scripts from .venv/bin
environment.yml	conda env create -p .conda	.conda/bin
package.json	npm / pnpm / yarn / bun install	node_modules/.bin
Cargo.toml, go.mod, Gemfile, composer.json, Project.toml, renv.lock, *.csproj, mix.exs, pom.xml, build.gradle	cargo fetch, go mod download, bundle install, …	build directories stay remote

The setup runs before a command only when a dependency file changed, and recom init does the first one.

• recom setup runs it on demand
• recom setup --clean rebuilds it from scratch
• recom --shell 'python3 -m ~' runs build commands by hand

Details in environments.

What a run does

1. Uploads files.

   • Upload to backend: Changed files with rsync.

   • Does not upload: Caches, .git/, local virtualenvs, build directories and secrets (.env, keys, cloud credentials).

   Nothing is ever deleted remotely. If the upload fails, nothing runs.

2. Sets up environment automatically

   If a dependency file changed since the last setup on that backend (see Dependencies).

3. Runs command.

   On the backend with its exact arguments, the backend's environment and toolchain, live stdout/stderr, stdin, and its exit code. Ctrl-C stops the remote process.

4. Downloads outputs

   Files the run created or changed, verified by SHA-256 and installed atomically. A file you edited locally during the run is never overwritten (the remote version goes to .recom/conflicts/). Large files (over 100 MB by default) stay remote until you recom pull them.

   If your laptop disconnects, outputs are collected by your next recom command.

Long jobs

recom --detach python3 -u train.py   # prints a job id; survives disconnects
recom jobs
recom logs <id> -f
recom attach <id>                    # live tmux session
recom stop <id>

A finished job's outputs come home with your next recom command, or recom pull.

More Information

recom --tty python3 repl.py	interactive programs (prompts, curses, colors)
recom --shell 'make | tee log.txt'	remote pipes and redirection (recom cmd > f writes f locally); manual environment setup
recom --no-sync nvidia-smi	skip the upload
recom --no-setup python3 x.py	skip the environment setup once
recom setup · recom update	prepare the backend now · update recom itself
recom status · recom env · recom doctor	pending outputs, remote toolchain/GPU, diagnostics

• CLI reference: every command, flag and exit code
• Sync and outputs: exactly what is uploaded, what counts as an output, conflicts
• Environments: how dependencies are installed on the backend, per language
• Configuration: .recom.toml, remote environment, Conda wrapper
• Architecture, security, limitations
• Troubleshooting · Examples

Limitations (v0.2): backends must be Linux. Local deletions are not propagated. While a detached job runs, it owns its project's replica, and ordinary runs of that project are refused until it ends (--no-sync still works). See limitations.

Development

make build              # bin/recom with embedded Linux helpers
make test               # unit tests (race detector)
make test-integration   # end-to-end tests against a throwaway local sshd

See CONTRIBUTING.md and SECURITY.md.

License

GPL-3.0