Metadata-Version: 2.4
Name: st-agent
Version: 0.3.2
Summary: SAGE remote agent — receives and executes file transfer instructions from the platform
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: cryptography>=42.0.0

# 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)

```bash
# 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)

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

### From source

```bash
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)

```bash
# 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

```bash
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

```bash
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)

```bash
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

```bash
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 │
└──────────────┘                  └──────────────┘
```
