st-agent — SAGE Remote Agent

Lightweight daemon that runs on destination servers. It connects to the SAGE platform via SSE, receives transfer instructions, and executes them using rsync/rclone.

Install

From wheel (air-gapped / no internet)

# On the build machine (has internet):
cd st-agent
pip install build
python -m build          # creates dist/st_agent-0.1.0-py3-none-any.whl

# Copy the wheel to the remote server, then:
pip install st_agent-0.1.0-py3-none-any.whl

From Git (direct)

pip install "git+https://github.com/sachin-techstax/sync_system.git#subdirectory=st-agent"

From source

git clone https://github.com/sachin-techstax/sync_system.git
cd sync_system/st-agent
pip install .

Prerequisites on remote server

• Python 3.10+
• rsync (for Linux-to-Linux transfers)
• rclone (optional, for cloud transfers)

# Ubuntu/Debian
sudo apt install -y rsync python3 python3-pip

# RHEL/CentOS
sudo yum install -y rsync python3 python3-pip

Usage

1. Register with the platform

st-agent register \
  --url http://<platform-ip>:6212 \
  --api-key <your-api-key> \
  --name "server-prod-01"

This generates an RSA keypair, registers with the platform, and saves config to ~/.st-agent/.

2. Start the agent

st-agent start

The agent will:

• Connect to the platform via SSE (Server-Sent Events)
• Send heartbeats every 15 seconds
• Execute transfer instructions (rsync, rclone)
• Report progress back to the platform in real-time

3. Run as a systemd service (recommended)

sudo tee /etc/systemd/system/st-agent.service << 'EOF'
[Unit]
Description=SAGE Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/st-agent start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now st-agent
sudo systemctl status st-agent

4. Check status

st-agent status

Configuration

Config is stored in ~/.st-agent/config.json after registration. The agent also stores its RSA keypair in ~/.st-agent/.

Architecture

Platform (hub)                    Remote Server
┌──────────────┐    SSE stream    ┌──────────────┐
│  FastAPI      │ ───────────────▸│  st-agent     │
│  /api/agents  │                 │  daemon       │
│               │◂─── heartbeat ──│               │
│               │◂─── progress ───│  rsync/rclone │
└──────────────┘                  └──────────────┘