sync-pilot

Interactive TUI tool for syncing projects to remote servers via rsync + SSH. Built for ML/DL training workflows.

Features

• Push/Pull — Sync code and checkpoints with rsync
• Remote Training — One-click push + launch training in tmux
• Monitor — GPU utilization, tmux session output, live attach, session management (kill/refresh)
• Status — Project overview with remote directory sizes and checkpoint counts
• Data Push — One-time upload for large datasets
• i18n — Auto-detects system locale (Chinese/English), override with --lang or SYNC_PILOT_LANG

Install

pip install sync-pilot
# or
uv add sync-pilot

Quick Start

# 1. Initialize config in your project directory
cd /path/to/your/project
sync-pilot init

# 2. Edit sync_config.yaml with your remote server info
vim sync_config.yaml

# 3. Launch interactive TUI
sync-pilot

Usage

sync-pilot              # Interactive TUI menu
sync-pilot init         # Generate config files in current directory
sync-pilot push         # Push code to remote
sync-pilot pull         # Pull checkpoints from remote
sync-pilot train        # Push + launch remote training in tmux
sync-pilot push-data    # One-time data upload
sync-pilot watch        # Monitor GPU & tmux sessions
sync-pilot status       # Project status overview

Options

-c, --config FILE    Config file path (default: auto-detect)
-p, --project NAME   Target project name
--lang zh|en         Force UI language
-V, --version        Show version

Configuration

sync_config.yaml:

remote_host: 1.2.3.4
remote_user: root
remote_port: 22          # Optional, default 22

projects:
  my_project:
    description: "My ML project"
    local_path: /home/user/workspace/project/
    remote_path: /mnt/workspace/project/
    exclude_file: rsync_exclude.txt   # Relative to this config file
    pull_directories:
      - checkpoints/
    checkpoint_patterns:              # For status search (default: *.pth, *.pt)
      - "*.pth"
      - "*.safetensors"

  training_data:
    description: "Training dataset (32GB)"
    local_path: /home/user/data/
    remote_path: /mnt/data/
    pull_only: true                   # Prevent accidental push

Config file auto-detection

sync-pilot looks for config files in this order:

1. sync_config.yaml
2. sync-pilot.yaml
3. .sync-pilot.yaml

Project options

Field	Required	Description
description	No	Human-readable project description
local_path	Yes	Local directory path (must end with /)
remote_path	Yes	Remote directory path
exclude_file	No	rsync exclude file, relative to config file
pull_directories	No	Directories to pull from remote
pull_only	No	Prevent push, allow pull only
checkpoint_patterns	No	File patterns for status search (default: ["*.pth", "*.pt"])

How it works

1. Push uses rsync -avz --progress --delete with exclude patterns to sync code
2. Train pushes code first, then creates a tmux session on the remote via ssh + tmux send-keys (ensures .bashrc is loaded for proper PATH)
3. Watch queries nvidia-smi and tmux capture-pane over SSH to display GPU status and training logs
4. Pull uses rsync without excludes to fetch all files from configured pull_directories

Requirements

• Python >= 3.10
• rsync and ssh available on PATH
• tmux on the remote server (for training/watch features)
• SSH key-based auth configured (recommended)

License

MIT

---

中文说明

sync-pilot 是一个交互式 TUI 工具，通过 rsync + SSH 同步项目到远端服务器，专为 ML/DL 训练工作流设计。

安装：pip install sync-pilot 或 uv add sync-pilot

快速开始：

sync-pilot init     # 生成配置文件
vim sync_config.yaml  # 编辑远端信息
sync-pilot          # 启动交互菜单

支持自动检测系统语言，也可通过 --lang zh 或 SYNC_PILOT_LANG=zh 强制使用中文界面。