simtooreal-agent 0.3.0

SIMTOOREAL — wrap any robot training command with full end-to-end analytics.

rpx-agent

Wrap any robot training command with one line and get full end-to-end analytics on simtooreal.com.

What it collects automatically - zero code changes to your training script:

Signal	How
Live logs (stdout + stderr)	Streamed in real-time
RL metrics (reward, KL, loss, entropy...)	Parsed from stdout - SB3, RSL-RL, Isaac Lab, CleanRL, generic
Termination reasons & reward components	Parsed from Episode_Termination/ and Episode_Reward/ lines
GPU / CPU / RAM	nvidia-smi + psutil every 60 s
Checkpoints / artifacts	File watcher: .pt, .pkl, .ckpt, .safetensors...
Environment snapshot	Python version, CUDA, GPU name, git SHA, detected simulator
Heartbeat	Every 30 s - run stays marked alive during Isaac Sim loading
Offline buffering	Events spooled to disk when backend unreachable; replayed automatically

---

Install

pip install rpx-agent
# Optional extras for richer system telemetry:
pip install "rpx-agent[full]"   # adds psutil + PyYAML

Local development:

pip install -e ./simtooreal-agent

---

Flow 1: pip install + rpx-agent run (recommended)

3 commands, then training is instrumented:

# 1. Authenticate
rpx-agent login --api-key YOUR_KEY

# 2. (optional) Initialise project config in your training directory
cd /path/to/your/robot/project
rpx-agent init

# 3. Wrap your existing training command - nothing else changes
rpx-agent run -- python train.py --num-envs 1024
rpx-agent run -- python train_headless.py --agent AnymalC --headless
rpx-agent run -- bash scripts/train.sh

Auto-detection: --task and --platform are inferred automatically. No need to add any flags unless you want to override.

rpx also works as a short alias: rpx run -- python train.py

All flags for rpx-agent run

--task TEXT          Experiment name (default: inferred from script filename)
--label TEXT         Human-readable label shown in dashboard
--platform TEXT      isaaclab | mujoco | gazebo | custom (auto-detected)
--run-id TEXT        Explicit run ID (auto-generated UUID if omitted)
--tags TEXT          Comma-separated tags
--watch-dir DIR      Extra dir to watch for checkpoints (repeatable)
--no-metrics         Disable stdout metric parsing
--no-sysinfo         Disable GPU/CPU telemetry
--no-artifacts       Disable checkpoint file detection
--batch-size N       Log events per HTTP batch (default: 80)
--flush-interval F   Seconds between log flushes (default: 1.5)

---

Flow 2: SSH connect (HPC / shared clusters)

For machines where you can't install packages (SLURM, university HPC):

1. In the SIMTOOREAL dashboard ? Remote Hosts ? Add SSH host
2. Paste your SSH key and remote training command
3. SIMTOOREAL SSHes in, runs your command, streams logs back
4. Same analytics pipeline - failure intelligence, sim-to-real, promotion gate

---

Flow 3: Docker self-host (on-prem enterprise)

cp .env.example .env
# Set SIMTOOREAL_API_KEY, SIMTOOREAL_DB_URL, JWT_SECRET in .env
docker compose up -d postgres backend frontend

Then use rpx-agent run pointed at your local backend:

export SIMTOOREAL_SERVER_URL=http://your-server:3001
rpx-agent run -- python train.py

---

Project config (simtooreal.yaml)

rpx-agent init creates this automatically. You can also write it manually:

project: anymal-locomotion
simulator: isaaclab
server_url: https://SIMTOOREAL-backend.fly.dev

watch_dirs:
  - .
  - logs/checkpoints

The agent searches for simtooreal.yaml from your current directory up to the filesystem root.

---

Environment variables

Variable	Aliases	Description
SIMTOOREAL_API_KEY	SIMTOOREAL_API_KEY, SIMTOOREAL_API_KEY	API key
SIMTOOREAL_SERVER_URL	SIMTOOREAL_SERVER_URL, SIMTOOREAL_SERVER_URL	Backend URL

---

Edge cases handled

• Backend unreachable at start - runs offline, all events spooled to ~/.simtooreal-agent/spool/, replayed when connection restored
• Binary / non-UTF-8 output (Isaac Sim OpenGL) - decoded with errors=replace, never crashes
• Long lines > 8 KB - truncated with ...[truncated] marker
• Orphan GPU processes on Ctrl+C - kills entire process group (SIGKILL on Linux, taskkill /T on Windows)
• Command not found - friendly error with PATH hint, exits 127
• Missing API key on production server - warns clearly with rpx-agent login instructions
• SLURM / multi-process training - wrap the srun or torchrun command directly
• Isaac Sim long startup (5-10 min silent) - heartbeat thread keeps run alive
• Rate limiting (HTTP 429) - automatic exponential backoff retry
• 401/403 auth errors - clear message with rpx-agent login instructions

---

Supported log formats (auto-parsed)

Framework	Detected signal
Stable Baselines3	| rollout/ep_rew_mean | 4.23 | table
RSL-RL / Isaac Lab	Learning iteration 100/1000 blocks
CleanRL	global_step=51200, episodic_return=4.23
Generic	reward=4.23 iteration=100 kl=0.012
SIMTOOREAL / rpx patch	[SIMTOOREAL] failure captured: base_contact rate=0.30
Episode labels	Episode_Termination/base_contact: 0.30

---

Publish to PyPI

python -m build ./simtooreal-agent
python -m twine upload simtooreal-agent/dist/*

Or just push a version tag - GitHub Actions auto-publishes:

git tag v0.2.1; git push origin v0.2.1