# Runicorn
**English** | [简体中文](README_zh.md)
[](https://pypi.org/project/runicorn/)
[](https://pypi.org/project/runicorn/)
[](LICENSE)
<p align="center">
<img src="docs/assets/icon.jpg" alt="Runicorn logo" width="360" />
</p>
Local, open-source experiment tracking and visualization. 100% offline. Professional ML experiment management; a modern self-hosted alternative to W&B.
## ✨ What's New
### v0.5.0 (Latest)
**🚀 Major Architecture Upgrade - Remote Viewer**
Runicorn 0.5.0 introduces an all-new **Remote Viewer** feature, adopting a VSCode Remote Development-style architecture that completely transforms how you access remote servers.
**Core Changes**:
- 🌐 **VSCode Remote Architecture** - Run Viewer on remote servers, access via SSH tunnel from local browser
- ⚡ **Real-time Access** - No sync needed, direct access to remote data, latency < 100ms
- 💾 **Zero Local Storage** - No need to mirror remote data locally, save massive disk space
- 🔧 **Auto Environment Detection** - Smart detection of remote Conda/Virtualenv environments, select and use
- 🔒 **Secure Connection** - SSH key/password authentication, automatic port forwarding, all communications encrypted
- 📊 **Full Feature Parity** - All features work identically in remote mode and local mode
**vs Old Remote Sync (0.4.x)**:
| Feature | 0.4.x File Sync | 0.5.0 Remote Viewer |
|---------|-----------------|--------------------|
| Data Transfer | Sync GB-level data | No sync, real-time access |
| Initial Wait | Hours (large datasets) | Seconds (connection startup) |
| Local Storage | Required (mirror copy) | Not required (zero usage) |
| Real-time | 5-10 min delay | Fully real-time (< 100ms) |
| Use Case | Occasional viewing | Daily development |
**Quick Try**:
```bash
runicorn viewer # Start local Viewer
# Open browser → Click "Remote" → Enter server info → Connect and use!
```
**UI & Quality Improvements**:
- 🎨 **Modern UI Animations** - Framer Motion powered components with configurable animations
- 🖼️ **Brand Identity** - Custom favicon with unicorn logo for better recognition
- 🌐 **Localization Polish** - Refined Chinese translations for better understanding
- 🐧 **WSL Compatibility** - Enhanced CPU monitoring for WSL/WSL2 environments
- 📝 **Persistent Logging** - Rotating log files (~/.runicorn/logs/viewer.log) for diagnostics
→ [Remote Viewer Complete Guide](docs/guides/en/REMOTE_VIEWER_GUIDE.md)
---
<details>
<summary><b>Version History</b></summary>
### v0.4.1
- 🆕 **System Information Panel** - View version, storage, and cache stats in Settings
- 🎨 **Dark Mode Improvements** - Better text readability across all pages
- ⚡ **Stability & Performance** - Optimized resource management and bug fixes
### v0.4.0
- 📦 **Model Versioning** - Complete Artifacts system for models and datasets
- 🔗 **Auto Lineage Tracking** - Track complete dependencies between artifacts and experiments
- 💾 **Smart Deduplication** - Hash-based content dedup, save 50-90% storage
- 🌳 **Lineage Visualization** - Interactive dependency graphs with ECharts
- 🏷️ **Version Aliases** - Semantic versioning (latest, production, etc.)
- 🔐 **Security Enhancements** - Triple-layer path traversal protection
- ⚡ **Performance Boost** - Metrics caching, 10-20x faster API
- 🎨 **UI Improvements** - Unified design system, optimized controls
</details>
## Core Features
- **Python Package**: `runicorn` - Universal SDK for any ML framework
- **Experiment Tracking**: Auto-log metrics, logs, environment info, smart status detection
- **Model Versioning**: Artifacts system - Git-like version control for ML assets
- **Web Viewer**: Modern interface, real-time charts and experiment comparison
- **Remote Viewer** 🆕: VSCode Remote-style architecture, real-time access to remote servers
- **Desktop App**: Native Windows application with auto-backend
- **GPU Monitoring**: Real-time GPU telemetry (requires `nvidia-smi`)
<table>
<tr>
<td width="50%"><img src="docs/assets/p1.png" alt="Experiments page" width="100%" /></td>
<td width="50%"><img src="docs/assets/p2.png" alt="Experiment detail" width="100%" /></td>
</tr>
<tr>
<td width="50%"><img src="docs/assets/p3.png" alt="Performance monitor" width="100%" /></td>
<td width="50%"><img src="docs/assets/p4.png" alt="Remote connection" width="100%" /></td>
</tr>
</table>
<p align="center">
<span style="color:#888; font-size: 12px;">UI Overview</span>
</p>
Features
--------
### 🏠 **Local & Secure**
- 100% local; data stays on your machine
- Zero telemetry; complete privacy
- Offline-capable after installation
### 🎯 **Smart Experiment Tracking**
- **Universal Best Metric** - Set any metric as primary indicator with auto-tracking
- **Intelligent Status Detection** - Automatic detection of crashed/interrupted experiments
- **Soft Delete & Recycle Bin** - Safe experiment management with restore capability
- **Environment Capture** - Automatic Git, dependencies, and system info tracking
### 📊 **Advanced Visualization**
- **Multi-run Comparison** - Overlay multiple experiments on single charts
- **Responsive Charts** - Adaptive layouts for any screen size
- **Real-time Updates** - Live logs and GPU monitoring via WebSocket
- **Multiple Export Formats** - CSV, Excel, TensorBoard, Markdown reports
### 🎨 **Modern Interface**
- **Tabbed Settings** - Comprehensive customization with live preview
- **Multi-language Support** - Full Chinese/English internationalization
- **Glass Morphism UI** - Beautiful modern design with customizable themes
- **Smart Layouts** - Automatic responsive design
### 🌐 **Remote Viewer** (🆕 v0.5.0 New Feature)
- **VSCode Remote Architecture** - Run Viewer process on remote server
- **Zero Sync Delay** - Direct access to remote data, no waiting for sync
- **Auto Environment Detection** - Smart identification of Conda, Virtualenv environments
- **SSH Tunnel** - Secure port forwarding, supports key and password authentication
- **Full Feature Support** - All features fully available in remote mode
Installation
------------
### Basic Installation
**For local use**:
```bash
pip install -U runicorn
```
**For remote server** (if using Remote Viewer):
```bash
# Also install Runicorn on remote Linux server
ssh user@remote-server
pip install -U runicorn
```
### System Requirements
- **Python**: 3.8+
- **Operating System**: Windows/Linux
- **Desktop App**: Windows-only (CLI/Viewer cross-platform)
- **Remote Viewer**: Remote server requires Linux (WSL supported)
Quick start
-----------------
### Start the viewer
```bash
runicorn viewer
# or custom params
runicorn viewer --host 127.0.0.1 --port 8000
# Open http://127.0.0.1:8000
```
Recommended: if you have Runicorn Desktop installed, just double-click to launch.
### Set the local storage root
- In Desktop app UI: top-right gear → Settings → Data Directory → Save Data Directory.
- Via CLI:
```bash
runicorn config --set-user-root "E:\\RunicornData"
runicorn config --show
```
The setting is written to `%APPDATA%\Runicorn\config.json` and can be edited directly.
### Usage example
```python
import runicorn as rn
import math, random
# Initialize experiment with automatic environment capture
run = rn.init(project="test_project", name="experiment_1", capture_env=True)
print(f"Created run: id={run.id} dir={run.run_dir}")
# Use rn.log_text to log info
rn.log_text(f"[info] Starting dummy run '{run.name}' (project={run.project})")
# Set primary metric for automatic best value tracking
rn.set_primary_metric("accuracy", mode="max") # or mode="min" for loss
stages = ["s1", "s2"]
for i in range(1, 101):
stage = stages[min((i - 1) // 33, len(stages) - 1)]
# Simulate training metrics
loss = max(0.02, 2.0 * math.exp(-0.02 * i) + random.uniform(-0.02, 0.02))
accuracy = min(95.0, 60 + i * 0.3 + random.uniform(-2, 2))
# Log metrics - best accuracy will be automatically tracked
rn.log({
"loss": round(loss, 4),
"accuracy": round(accuracy, 2),
"learning_rate": 0.001 * (0.95 ** i)
}, stage=stage)
# Summary metrics
rn.summary({
"final_accuracy": 92.1,
"total_epochs": 100,
"notes": "Baseline model with improved architecture"
})
rn.finish() # Best metric automatically saved
```
### Advanced features
#### Data export (optional)
```python
# init
exporter = rn.MetricsExporter(run.run_dir)
# Your training code
exporter.to_excel("results.xlsx", include_charts=True)
exporter.generate_report("report.md", format="markdown")
```
#### Explicitly override the storage root (optional)
```python
run = rn.init(project="demo", name="exp1", storage="E:\\RunicornData")
```
Storage root precedence (high → low):
1. `runicorn.init(storage=...)`
2. Environment variable `RUNICORN_DIR`
3. Per-user config `user_root_dir` (set via `runicorn config` or web UI)
## 🌐 Remote Viewer User Guide
### What is Remote Viewer?
Remote Viewer adopts a **VSCode Remote Development-style architecture**, allowing you to:
- Run **Viewer process on remote server**
- Access via **SSH tunnel** in local browser
- **Real-time viewing** of remote experiment data, no sync needed
### 5-Minute Quick Start
#### Step 1: Ensure Runicorn is Installed on Remote Server
```bash
# SSH login to remote server
ssh user@gpu-server.com
# Install Runicorn
pip install runicorn
# Or in conda environment
conda activate your-env
pip install runicorn
```
#### Step 2: Start Local Viewer
```bash
# On local machine
runicorn viewer
# Browser automatically opens http://localhost:23300
```
#### Step 3: Connect to Remote Server
1. Click **"Remote"** button in top menu bar
2. Fill in SSH connection info:
- **Host**: `gpu-server.com`
- **Port**: `22`
- **Username**: `your-username`
- **Authentication**: SSH key or password
3. Click **"Connect to Server"**
#### Step 4: Select Python Environment
System will auto-detect Python environments on remote server, showing a list:
| Environment | Python Version | Runicorn Version | Storage Root |
|-------------|----------------|------------------|-------------|
| base | Python 3.10.8 | 0.5.0 | /home/user/RunicornData |
| pytorch-env | Python 3.9.15 | 0.5.0 | /data/experiments |
Select the environment you want to use, click **"Use This Environment"**
#### Step 5: Start Remote Viewer
Review configuration summary, click **"Start Remote Viewer"**
```
Remote Server: gpu-server.com
Python Environment: pytorch-env
Runicorn Version: 0.5.0
Storage Root: /data/experiments
```
#### Step 6: Access Remote Data
Automatically opens new browser tab, address like: `http://localhost:8081`
Browse remote experiment data just like using local Viewer!
### FAQ
**Q: Does it support Windows remote servers?**
A: Currently only supports Linux remote servers (including WSL).
**Q: Can I connect to multiple servers simultaneously?**
A: Yes, each connection uses a different local port.
**Q: Will data be lost after disconnecting?**
A: No, data remains on the remote server. Reconnect to continue accessing.
→ **Complete Guide**: [Remote Viewer User Guide](docs/guides/en/REMOTE_VIEWER_GUIDE.md)
---
<details>
<summary><b>⚠️ Old Remote Sync (Deprecated)</b></summary>
> **Deprecated in v0.5.0**
>
> The 0.4.x file sync feature has been replaced by Remote Viewer.
> Please use the new feature above for better, faster, simpler experience!
>
> **Migration Guide**: [0.4.x → 0.5.0 Migration Guide](docs/guides/en/MIGRATION_GUIDE_v0.4_to_v0.5.md)
Old file sync method still works but is no longer recommended:
- Open the "Remote" page in top navigation
- Steps:
1) Connect: enter `host`, `port`, `username`, `password/key`
2) Browse remote directories and select the correct level
3) Click "Sync this directory"
</details>
Desktop app (Windows)
---------------------
- Install from GitHub Releases (recommended for end users), or build locally.
- Prerequisites: Node.js 18+; Rust & Cargo (stable); Python 3.8+; NSIS (for installer packaging).
- Build locally (creates an NSIS installer):
```powershell
# From repo root
powershell -ExecutionPolicy Bypass -File .\desktop\tauri\build_release.ps1 -Bundles nsis
# Installer output:
# desktop/tauri/src-tauri/target/release/bundle/nsis/Runicorn Desktop_<version>_x64-setup.exe
```
- After installation, launch "Runicorn Desktop".
- First run: open the gear icon (top-right) → Settings → Data Directory, choose a writable path (e.g., `D:\RunicornData`), then Save.
- The desktop app auto-starts a local backend and opens the UI.
Privacy & Offline
-----------------
- No telemetry. The viewer only reads local files (JSON/JSONL and media).
- Bundled UI allows using the viewer without Node.js at runtime.
Storage layout
--------------
```
user_root_dir/
<project>/
<name>/
runs/
<run_id>/
meta.json
status.json
summary.json
events.jsonl
logs.txt
media/
```
API Documentation
-----------------
- **REST API Reference**: See [docs/api/](docs/api/) for complete API documentation
- **Interactive Docs**: Open `http://127.0.0.1:23300/docs` after starting viewer (auto-generated by FastAPI)
- **Quick Reference**: [docs/api/QUICK_REFERENCE.md](docs/api/QUICK_REFERENCE.md) - Common operations cheat sheet
Community
---------
- See `CONTRIBUTING.md` for dev setup, style, and release flow.
- See `SECURITY.md` for private vulnerability reporting.
- See `CHANGELOG.md` for version history.
Contributing
------------
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
License
-------
MIT License - see [LICENSE](LICENSE) file.
AI Use
-------
The project is mainly developed by Claude models.
---
**Author**: Runicorn Development Team
**Version**: v0.5.0
**Last Updated**: 2025-10-28
Raw data
{
"_id": null,
"home_page": null,
"name": "runicorn",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "experiment-tracking, mlops, training, visualization, fastapi, wandb-alternative, self-hosted",
"author": "Runicorn Authors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b1/ea/fd363abd4e1910e01948a796b9d42850c59e148b941181e73dd83b0fbd91/runicorn-0.5.0.tar.gz",
"platform": null,
"description": "# Runicorn\r\n\r\n**English** | [\u7b80\u4f53\u4e2d\u6587](README_zh.md)\r\n\r\n[](https://pypi.org/project/runicorn/)\r\n[](https://pypi.org/project/runicorn/)\r\n[](LICENSE)\r\n\r\n<p align=\"center\">\r\n <img src=\"docs/assets/icon.jpg\" alt=\"Runicorn logo\" width=\"360\" />\r\n</p>\r\n\r\nLocal, open-source experiment tracking and visualization. 100% offline. Professional ML experiment management; a modern self-hosted alternative to W&B.\r\n\r\n## \u2728 What's New\r\n\r\n### v0.5.0 (Latest)\r\n\r\n**\ud83d\ude80 Major Architecture Upgrade - Remote Viewer**\r\n\r\nRunicorn 0.5.0 introduces an all-new **Remote Viewer** feature, adopting a VSCode Remote Development-style architecture that completely transforms how you access remote servers.\r\n\r\n**Core Changes**:\r\n- \ud83c\udf10 **VSCode Remote Architecture** - Run Viewer on remote servers, access via SSH tunnel from local browser\r\n- \u26a1 **Real-time Access** - No sync needed, direct access to remote data, latency < 100ms\r\n- \ud83d\udcbe **Zero Local Storage** - No need to mirror remote data locally, save massive disk space\r\n- \ud83d\udd27 **Auto Environment Detection** - Smart detection of remote Conda/Virtualenv environments, select and use\r\n- \ud83d\udd12 **Secure Connection** - SSH key/password authentication, automatic port forwarding, all communications encrypted\r\n- \ud83d\udcca **Full Feature Parity** - All features work identically in remote mode and local mode\r\n\r\n**vs Old Remote Sync (0.4.x)**:\r\n\r\n| Feature | 0.4.x File Sync | 0.5.0 Remote Viewer |\r\n|---------|-----------------|--------------------|\r\n| Data Transfer | Sync GB-level data | No sync, real-time access |\r\n| Initial Wait | Hours (large datasets) | Seconds (connection startup) |\r\n| Local Storage | Required (mirror copy) | Not required (zero usage) |\r\n| Real-time | 5-10 min delay | Fully real-time (< 100ms) |\r\n| Use Case | Occasional viewing | Daily development |\r\n\r\n**Quick Try**:\r\n```bash\r\nrunicorn viewer # Start local Viewer\r\n# Open browser \u2192 Click \"Remote\" \u2192 Enter server info \u2192 Connect and use!\r\n```\r\n\r\n**UI & Quality Improvements**:\r\n- \ud83c\udfa8 **Modern UI Animations** - Framer Motion powered components with configurable animations\r\n- \ud83d\uddbc\ufe0f **Brand Identity** - Custom favicon with unicorn logo for better recognition\r\n- \ud83c\udf10 **Localization Polish** - Refined Chinese translations for better understanding\r\n- \ud83d\udc27 **WSL Compatibility** - Enhanced CPU monitoring for WSL/WSL2 environments\r\n- \ud83d\udcdd **Persistent Logging** - Rotating log files (~/.runicorn/logs/viewer.log) for diagnostics\r\n\r\n\u2192 [Remote Viewer Complete Guide](docs/guides/en/REMOTE_VIEWER_GUIDE.md)\r\n\r\n---\r\n\r\n<details>\r\n<summary><b>Version History</b></summary>\r\n\r\n### v0.4.1\r\n\r\n- \ud83c\udd95 **System Information Panel** - View version, storage, and cache stats in Settings\r\n- \ud83c\udfa8 **Dark Mode Improvements** - Better text readability across all pages\r\n- \u26a1 **Stability & Performance** - Optimized resource management and bug fixes\r\n\r\n### v0.4.0\r\n\r\n- \ud83d\udce6 **Model Versioning** - Complete Artifacts system for models and datasets\r\n- \ud83d\udd17 **Auto Lineage Tracking** - Track complete dependencies between artifacts and experiments\r\n- \ud83d\udcbe **Smart Deduplication** - Hash-based content dedup, save 50-90% storage\r\n- \ud83c\udf33 **Lineage Visualization** - Interactive dependency graphs with ECharts\r\n- \ud83c\udff7\ufe0f **Version Aliases** - Semantic versioning (latest, production, etc.)\r\n- \ud83d\udd10 **Security Enhancements** - Triple-layer path traversal protection\r\n- \u26a1 **Performance Boost** - Metrics caching, 10-20x faster API\r\n- \ud83c\udfa8 **UI Improvements** - Unified design system, optimized controls\r\n\r\n</details>\r\n\r\n## Core Features\r\n\r\n- **Python Package**: `runicorn` - Universal SDK for any ML framework\r\n- **Experiment Tracking**: Auto-log metrics, logs, environment info, smart status detection\r\n- **Model Versioning**: Artifacts system - Git-like version control for ML assets\r\n- **Web Viewer**: Modern interface, real-time charts and experiment comparison\r\n- **Remote Viewer** \ud83c\udd95: VSCode Remote-style architecture, real-time access to remote servers\r\n- **Desktop App**: Native Windows application with auto-backend\r\n- **GPU Monitoring**: Real-time GPU telemetry (requires `nvidia-smi`)\r\n\r\n\r\n<table>\r\n <tr>\r\n <td width=\"50%\"><img src=\"docs/assets/p1.png\" alt=\"Experiments page\" width=\"100%\" /></td>\r\n <td width=\"50%\"><img src=\"docs/assets/p2.png\" alt=\"Experiment detail\" width=\"100%\" /></td>\r\n </tr>\r\n <tr>\r\n <td width=\"50%\"><img src=\"docs/assets/p3.png\" alt=\"Performance monitor\" width=\"100%\" /></td>\r\n <td width=\"50%\"><img src=\"docs/assets/p4.png\" alt=\"Remote connection\" width=\"100%\" /></td>\r\n </tr>\r\n</table>\r\n\r\n<p align=\"center\">\r\n <span style=\"color:#888; font-size: 12px;\">UI Overview</span>\r\n</p>\r\n\r\n\r\nFeatures\r\n--------\r\n\r\n### \ud83c\udfe0 **Local & Secure**\r\n- 100% local; data stays on your machine\r\n- Zero telemetry; complete privacy\r\n- Offline-capable after installation\r\n\r\n### \ud83c\udfaf **Smart Experiment Tracking**\r\n- **Universal Best Metric** - Set any metric as primary indicator with auto-tracking\r\n- **Intelligent Status Detection** - Automatic detection of crashed/interrupted experiments\r\n- **Soft Delete & Recycle Bin** - Safe experiment management with restore capability\r\n- **Environment Capture** - Automatic Git, dependencies, and system info tracking\r\n\r\n### \ud83d\udcca **Advanced Visualization**\r\n- **Multi-run Comparison** - Overlay multiple experiments on single charts\r\n- **Responsive Charts** - Adaptive layouts for any screen size\r\n- **Real-time Updates** - Live logs and GPU monitoring via WebSocket\r\n- **Multiple Export Formats** - CSV, Excel, TensorBoard, Markdown reports\r\n\r\n### \ud83c\udfa8 **Modern Interface**\r\n- **Tabbed Settings** - Comprehensive customization with live preview\r\n- **Multi-language Support** - Full Chinese/English internationalization\r\n- **Glass Morphism UI** - Beautiful modern design with customizable themes\r\n- **Smart Layouts** - Automatic responsive design\r\n\r\n### \ud83c\udf10 **Remote Viewer** (\ud83c\udd95 v0.5.0 New Feature)\r\n- **VSCode Remote Architecture** - Run Viewer process on remote server\r\n- **Zero Sync Delay** - Direct access to remote data, no waiting for sync\r\n- **Auto Environment Detection** - Smart identification of Conda, Virtualenv environments\r\n- **SSH Tunnel** - Secure port forwarding, supports key and password authentication\r\n- **Full Feature Support** - All features fully available in remote mode\r\n\r\n\r\nInstallation\r\n------------\r\n\r\n### Basic Installation\r\n\r\n**For local use**:\r\n```bash\r\npip install -U runicorn\r\n```\r\n\r\n**For remote server** (if using Remote Viewer):\r\n```bash\r\n# Also install Runicorn on remote Linux server\r\nssh user@remote-server\r\npip install -U runicorn\r\n```\r\n\r\n### System Requirements\r\n\r\n- **Python**: 3.8+\r\n- **Operating System**: Windows/Linux\r\n- **Desktop App**: Windows-only (CLI/Viewer cross-platform)\r\n- **Remote Viewer**: Remote server requires Linux (WSL supported)\r\n\r\nQuick start\r\n-----------------\r\n\r\n### Start the viewer\r\n\r\n```bash\r\nrunicorn viewer\r\n# or custom params\r\nrunicorn viewer --host 127.0.0.1 --port 8000\r\n# Open http://127.0.0.1:8000\r\n```\r\n\r\nRecommended: if you have Runicorn Desktop installed, just double-click to launch.\r\n\r\n### Set the local storage root\r\n\r\n- In Desktop app UI: top-right gear \u2192 Settings \u2192 Data Directory \u2192 Save Data Directory.\r\n\r\n- Via CLI:\r\n\r\n```bash\r\nrunicorn config --set-user-root \"E:\\\\RunicornData\"\r\nrunicorn config --show\r\n```\r\n\r\nThe setting is written to `%APPDATA%\\Runicorn\\config.json` and can be edited directly.\r\n\r\n### Usage example\r\n\r\n```python\r\nimport runicorn as rn\r\nimport math, random\r\n\r\n# Initialize experiment with automatic environment capture\r\nrun = rn.init(project=\"test_project\", name=\"experiment_1\", capture_env=True)\r\nprint(f\"Created run: id={run.id} dir={run.run_dir}\")\r\n\r\n# Use rn.log_text to log info\r\nrn.log_text(f\"[info] Starting dummy run '{run.name}' (project={run.project})\")\r\n\r\n# Set primary metric for automatic best value tracking\r\nrn.set_primary_metric(\"accuracy\", mode=\"max\") # or mode=\"min\" for loss\r\n\r\nstages = [\"s1\", \"s2\"]\r\nfor i in range(1, 101):\r\n stage = stages[min((i - 1) // 33, len(stages) - 1)]\r\n \r\n # Simulate training metrics\r\n loss = max(0.02, 2.0 * math.exp(-0.02 * i) + random.uniform(-0.02, 0.02))\r\n accuracy = min(95.0, 60 + i * 0.3 + random.uniform(-2, 2))\r\n \r\n # Log metrics - best accuracy will be automatically tracked\r\n rn.log({\r\n \"loss\": round(loss, 4),\r\n \"accuracy\": round(accuracy, 2),\r\n \"learning_rate\": 0.001 * (0.95 ** i)\r\n }, stage=stage)\r\n\r\n# Summary metrics\r\nrn.summary({\r\n \"final_accuracy\": 92.1,\r\n \"total_epochs\": 100,\r\n \"notes\": \"Baseline model with improved architecture\"\r\n})\r\n\r\nrn.finish() # Best metric automatically saved\r\n```\r\n\r\n### Advanced features\r\n\r\n#### Data export (optional)\r\n```python\r\n# init\r\nexporter = rn.MetricsExporter(run.run_dir)\r\n# Your training code\r\nexporter.to_excel(\"results.xlsx\", include_charts=True)\r\nexporter.generate_report(\"report.md\", format=\"markdown\")\r\n```\r\n\r\n#### Explicitly override the storage root (optional)\r\n\r\n```python\r\nrun = rn.init(project=\"demo\", name=\"exp1\", storage=\"E:\\\\RunicornData\")\r\n```\r\n\r\nStorage root precedence (high \u2192 low):\r\n\r\n1. `runicorn.init(storage=...)`\r\n2. Environment variable `RUNICORN_DIR`\r\n3. Per-user config `user_root_dir` (set via `runicorn config` or web UI)\r\n\r\n\r\n## \ud83c\udf10 Remote Viewer User Guide\r\n\r\n### What is Remote Viewer?\r\n\r\nRemote Viewer adopts a **VSCode Remote Development-style architecture**, allowing you to:\r\n- Run **Viewer process on remote server**\r\n- Access via **SSH tunnel** in local browser\r\n- **Real-time viewing** of remote experiment data, no sync needed\r\n\r\n### 5-Minute Quick Start\r\n\r\n#### Step 1: Ensure Runicorn is Installed on Remote Server\r\n\r\n```bash\r\n# SSH login to remote server\r\nssh user@gpu-server.com\r\n\r\n# Install Runicorn\r\npip install runicorn\r\n# Or in conda environment\r\nconda activate your-env\r\npip install runicorn\r\n```\r\n\r\n#### Step 2: Start Local Viewer\r\n\r\n```bash\r\n# On local machine\r\nrunicorn viewer\r\n# Browser automatically opens http://localhost:23300\r\n```\r\n\r\n#### Step 3: Connect to Remote Server\r\n\r\n1. Click **\"Remote\"** button in top menu bar\r\n2. Fill in SSH connection info:\r\n - **Host**: `gpu-server.com`\r\n - **Port**: `22`\r\n - **Username**: `your-username`\r\n - **Authentication**: SSH key or password\r\n3. Click **\"Connect to Server\"**\r\n\r\n#### Step 4: Select Python Environment\r\n\r\nSystem will auto-detect Python environments on remote server, showing a list:\r\n\r\n| Environment | Python Version | Runicorn Version | Storage Root |\r\n|-------------|----------------|------------------|-------------|\r\n| base | Python 3.10.8 | 0.5.0 | /home/user/RunicornData |\r\n| pytorch-env | Python 3.9.15 | 0.5.0 | /data/experiments |\r\n\r\nSelect the environment you want to use, click **\"Use This Environment\"**\r\n\r\n#### Step 5: Start Remote Viewer\r\n\r\nReview configuration summary, click **\"Start Remote Viewer\"**\r\n\r\n```\r\nRemote Server: gpu-server.com\r\nPython Environment: pytorch-env\r\nRunicorn Version: 0.5.0\r\nStorage Root: /data/experiments\r\n```\r\n\r\n#### Step 6: Access Remote Data\r\n\r\nAutomatically opens new browser tab, address like: `http://localhost:8081`\r\n\r\nBrowse remote experiment data just like using local Viewer!\r\n\r\n### FAQ\r\n\r\n**Q: Does it support Windows remote servers?** \r\nA: Currently only supports Linux remote servers (including WSL).\r\n\r\n**Q: Can I connect to multiple servers simultaneously?** \r\nA: Yes, each connection uses a different local port.\r\n\r\n**Q: Will data be lost after disconnecting?** \r\nA: No, data remains on the remote server. Reconnect to continue accessing.\r\n\r\n\u2192 **Complete Guide**: [Remote Viewer User Guide](docs/guides/en/REMOTE_VIEWER_GUIDE.md)\r\n\r\n---\r\n\r\n<details>\r\n<summary><b>\u26a0\ufe0f Old Remote Sync (Deprecated)</b></summary>\r\n\r\n> **Deprecated in v0.5.0** \r\n> \r\n> The 0.4.x file sync feature has been replaced by Remote Viewer. \r\n> Please use the new feature above for better, faster, simpler experience!\r\n> \r\n> **Migration Guide**: [0.4.x \u2192 0.5.0 Migration Guide](docs/guides/en/MIGRATION_GUIDE_v0.4_to_v0.5.md)\r\n\r\nOld file sync method still works but is no longer recommended:\r\n\r\n- Open the \"Remote\" page in top navigation\r\n- Steps:\r\n 1) Connect: enter `host`, `port`, `username`, `password/key`\r\n 2) Browse remote directories and select the correct level\r\n 3) Click \"Sync this directory\"\r\n\r\n</details>\r\n\r\nDesktop app (Windows)\r\n---------------------\r\n- Install from GitHub Releases (recommended for end users), or build locally.\r\n- Prerequisites: Node.js 18+; Rust & Cargo (stable); Python 3.8+; NSIS (for installer packaging).\r\n- Build locally (creates an NSIS installer):\r\n\r\n ```powershell\r\n # From repo root\r\n powershell -ExecutionPolicy Bypass -File .\\desktop\\tauri\\build_release.ps1 -Bundles nsis\r\n # Installer output:\r\n # desktop/tauri/src-tauri/target/release/bundle/nsis/Runicorn Desktop_<version>_x64-setup.exe\r\n ```\r\n\r\n- After installation, launch \"Runicorn Desktop\".\r\n - First run: open the gear icon (top-right) \u2192 Settings \u2192 Data Directory, choose a writable path (e.g., `D:\\RunicornData`), then Save.\r\n - The desktop app auto-starts a local backend and opens the UI.\r\n\r\nPrivacy & Offline\r\n-----------------\r\n- No telemetry. The viewer only reads local files (JSON/JSONL and media).\r\n- Bundled UI allows using the viewer without Node.js at runtime.\r\n\r\nStorage layout\r\n--------------\r\n```\r\nuser_root_dir/\r\n <project>/\r\n <name>/\r\n runs/\r\n <run_id>/\r\n meta.json\r\n status.json\r\n summary.json\r\n events.jsonl\r\n logs.txt\r\n media/\r\n```\r\n\r\nAPI Documentation\r\n-----------------\r\n- **REST API Reference**: See [docs/api/](docs/api/) for complete API documentation\r\n- **Interactive Docs**: Open `http://127.0.0.1:23300/docs` after starting viewer (auto-generated by FastAPI)\r\n- **Quick Reference**: [docs/api/QUICK_REFERENCE.md](docs/api/QUICK_REFERENCE.md) - Common operations cheat sheet\r\n\r\nCommunity\r\n---------\r\n- See `CONTRIBUTING.md` for dev setup, style, and release flow.\r\n- See `SECURITY.md` for private vulnerability reporting.\r\n- See `CHANGELOG.md` for version history.\r\n\r\nContributing\r\n------------\r\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\r\n\r\nLicense\r\n-------\r\nMIT License - see [LICENSE](LICENSE) file.\r\n\r\nAI Use\r\n-------\r\nThe project is mainly developed by Claude models.\r\n\r\n---\r\n\r\n**Author**: Runicorn Development Team \r\n**Version**: v0.5.0 \r\n**Last Updated**: 2025-10-28\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Local experiment tracking with model versioning - self-hosted W&B alternative with Artifacts",
"version": "0.5.0",
"project_urls": {
"Changelog": "https://pypi.org/project/runicorn/#history",
"Homepage": "https://pypi.org/project/runicorn/"
},
"split_keywords": [
"experiment-tracking",
" mlops",
" training",
" visualization",
" fastapi",
" wandb-alternative",
" self-hosted"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e13e3adb0dc8a2b2dda508d6648508f191a5c7b4ed143e4bcf6a02df4ea483e8",
"md5": "47738111af4cb7161069fd81111087b8",
"sha256": "a48d8f72b080541f1a58c019507726d69fbec7817c4ad3e403df2b836e76f8fa"
},
"downloads": -1,
"filename": "runicorn-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47738111af4cb7161069fd81111087b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1190480,
"upload_time": "2025-10-28T12:30:47",
"upload_time_iso_8601": "2025-10-28T12:30:47.254018Z",
"url": "https://files.pythonhosted.org/packages/e1/3e/3adb0dc8a2b2dda508d6648508f191a5c7b4ed143e4bcf6a02df4ea483e8/runicorn-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1eafd363abd4e1910e01948a796b9d42850c59e148b941181e73dd83b0fbd91",
"md5": "07c6259bfd2afb890d21f32912dfcdb9",
"sha256": "b3fdf420b67b1c5c72c9f4bccbc38a987eab548ab4fd5f8a43409a3e755a8b37"
},
"downloads": -1,
"filename": "runicorn-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "07c6259bfd2afb890d21f32912dfcdb9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1172988,
"upload_time": "2025-10-28T12:30:50",
"upload_time_iso_8601": "2025-10-28T12:30:50.415567Z",
"url": "https://files.pythonhosted.org/packages/b1/ea/fd363abd4e1910e01948a796b9d42850c59e148b941181e73dd83b0fbd91/runicorn-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 12:30:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "runicorn"
}
JSON