English | 简体中文
A Rust SDK and CLI tool for mihomo proxy management with service lifecycle management, configuration handling, and real-time monitoring.
- 🔧 Version Management - Install, update, and switch between mihomo versions (rustup-like experience)
- ⚙️ Configuration Management - Manage multiple configuration profiles with validation
- 🚀 Service Lifecycle - Start, stop, restart mihomo service with PID management
- 🔄 Proxy Operations - List, switch, and test proxy nodes and groups
- 📊 Real-time Monitoring - Stream logs, traffic statistics, and memory usage
- 🔌 Connection Management - Monitor, filter, and close active connections in real-time
- 📦 SDK Library - Use as a library in your Rust applications
- 🖥️ CLI Tool - Command-line interface for easy management
Add to your Cargo.toml:
[dependencies]
mihomo-rs = "*"cargo install mihomo-rsuse mihomo_rs::{Channel, ConfigManager, MihomoClient, ProxyManager, ServiceManager, VersionManager, ConnectionManager, Result};
#[tokio::main]
async fn main() -> Result<()> {
// 1. Install mihomo
let vm = VersionManager::new()?;
vm.install_channel(Channel::Stable).await?;
// 2. Setup configuration
let cm = ConfigManager::new()?;
cm.ensure_default_config().await?;
let controller_url = cm.ensure_external_controller().await?;
// 3. Start service
let binary = vm.get_binary_path(None).await?;
let config = cm.get_current_path().await?;
let sm = ServiceManager::new(binary, config);
sm.start().await?;
// 4. Use proxy manager
let client = MihomoClient::new(&controller_url, None)?;
let pm = ProxyManager::new(client.clone());
// List proxy groups
let groups = pm.list_groups().await?;
for group in groups {
println!("{}: {} ({})", group.name, group.now, group.group_type);
}
// Switch proxy
pm.switch("GLOBAL", "proxy-name").await?;
// 5. Monitor connections
let conn_mgr = ConnectionManager::new(client.clone());
// List active connections
let connections = conn_mgr.list().await?;
println!("Active connections: {}", connections.len());
// Filter connections by host
let filtered = conn_mgr.filter_by_host("example.com").await?;
// Close specific connection
if let Some(conn) = connections.first() {
conn_mgr.close(&conn.id).await?;
}
// 6. Stream real-time traffic
let mut traffic_rx = client.stream_traffic().await?;
while let Some(traffic) = traffic_rx.recv().await {
println!("Upload: {} KB/s, Download: {} KB/s",
traffic.up / 1024, traffic.down / 1024);
}
Ok(())
}# Install mihomo
mihomo-rs install stable
# Start service
mihomo-rs start
# List proxies
mihomo-rs proxy list
# Switch proxy
mihomo-rs proxy switch GLOBAL proxy-name
# Stream logs (with level filter)
mihomo-rs logs --level info
# Stream traffic statistics
mihomo-rs traffic
# Show memory usage
mihomo-rs memory
# List active connections
mihomo-rs connection list
# Show connection statistics
mihomo-rs connection stats
# Stream connections in real-time
mihomo-rs connection stream
# Close specific connection
mihomo-rs connection close <connection-id>
# Close all connections
mihomo-rs connection close-all --forceThe examples/ directory includes comprehensive examples:
- hello_mihomo.rs - Minimal example
- basic_workflow.rs - Complete beginner workflow
- install_version.rs - Install specific version
- install_by_channel.rs - Install from channel
- list_versions.rs - List installed versions
- manage_versions.rs - Version lifecycle
- manage_profiles.rs - Profile management
- custom_config.rs - Custom configuration
- external_controller.rs - Controller setup
- service_lifecycle.rs - Start/stop/restart
- service_status.rs - Check status
- auto_restart.rs - Auto-restart logic
- list_proxies.rs - List all proxies
- list_groups.rs - List proxy groups
- switch_proxy.rs - Switch proxy
- test_delay.rs - Test latency
- current_proxy.rs - Current selections
- stream_logs.rs - Real-time logs
- stream_logs_filtered.rs - Filtered logs
- stream_traffic.rs - Traffic monitoring
- memory_usage.rs - Memory usage
- list_connections.rs - List active connections with filtering
- close_connections.rs - Close connections by ID, host, or process
- stream_connections.rs - Real-time connection monitoring
- custom_home_dir.rs - Custom home directory
- complete_workflow.rs - Full application
- error_handling.rs - Error patterns
- concurrent_operations.rs - Parallel ops
- first_time_setup.rs - First-time setup
- migration_helper.rs - Migration guide
Run any example with:
cargo run --example hello_mihomoSee examples/README.md for detailed documentation.
mihomo-rs/
├── src/
│ ├── core/ # Core HTTP/WebSocket client and types
│ │ ├── client.rs # MihomoClient (HTTP + WebSocket)
│ │ ├── types.rs # Data structures
│ │ ├── error.rs # Error types
│ │ ├── port.rs # Port utilities
│ │ └── home.rs # Home directory management
│ ├── version/ # Version management
│ │ ├── manager.rs # VersionManager
│ │ ├── channel.rs # Channel (Stable/Beta/Nightly)
│ │ └── download.rs # Binary downloader
│ ├── config/ # Configuration management
│ │ ├── manager.rs # ConfigManager
│ │ └── profile.rs # Profile struct
│ ├── service/ # Service lifecycle
│ │ ├── manager.rs # ServiceManager
│ │ └── process.rs # Process utilities
│ ├── proxy/ # Proxy operations
│ │ ├── manager.rs # ProxyManager
│ │ └── test.rs # Delay testing
│ ├── connection/ # Connection management
│ │ └── manager.rs # ConnectionManager
│ └── cli/ # CLI application
├── examples/ # 31 comprehensive examples
└── tests/ # Integration tests
| Module | Description |
|---|---|
MihomoClient |
HTTP/WebSocket client for mihomo API |
VersionManager |
Install and manage mihomo versions |
ConfigManager |
Manage configuration profiles |
ServiceManager |
Control service lifecycle |
ProxyManager |
High-level proxy operations |
ConnectionManager |
Monitor and manage active connections |
| Type | Description |
|---|---|
Version |
Mihomo version information |
ProxyNode |
Individual proxy node |
ProxyGroup |
Proxy group (Selector, URLTest, etc.) |
TrafficData |
Upload/download statistics |
MemoryData |
Memory usage information |
Channel |
Release channel (Stable/Beta/Nightly) |
Connection |
Active connection information |
ConnectionSnapshot |
Real-time connections snapshot |
ConnectionMetadata |
Connection metadata (source, destination, process, etc.) |
// Convenience functions for common operations
use mihomo_rs::{install_mihomo, start_service, stop_service, switch_proxy};
// Install mihomo
install_mihomo(None).await?; // Latest stable
// Service management
start_service(&config_path).await?;
stop_service(&config_path).await?;
// Proxy switching
switch_proxy("GLOBAL", "proxy-name").await?;mihomo-rs stores data in ~/.config/mihomo-rs/ (or $MIHOMO_HOME):
~/.config/mihomo-rs/
├── versions/ # Installed mihomo binaries
│ ├── v1.18.0/
│ └── v1.18.9/
├── configs/ # Configuration profiles
│ ├── default.yaml
│ └── custom.yaml
├── config.toml # mihomo-rs settings
└── mihomo.pid # Service PID file
Set via environment variable:
export MIHOMO_HOME=/custom/pathOr programmatically:
use mihomo_rs::{VersionManager, ConfigManager};
use std::path::PathBuf;
let home = PathBuf::from("/custom/path");
let vm = VersionManager::with_home(home.clone())?;
let cm = ConfigManager::with_home(home)?;# ~/.config/mihomo-rs/configs/default.yaml
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
proxies:
- name: "proxy1"
type: ss
server: server.example.com
port: 443
cipher: aes-256-gcm
password: password
proxy-groups:
- name: "GLOBAL"
type: select
proxies:
- proxy1git clone https://github.com/DINGDANGMAOUP/mihomo-rs
cd mihomo-rs
cargo build --releasecargo test# Enable logging for debugging
RUST_LOG=debug cargo run --example basic_workflow- Automate mihomo deployment and updates
- Monitor multiple mihomo instances
- Centralized configuration management
- Integrate proxy management into applications
- Real-time traffic monitoring
- Programmatic proxy switching
- Manage multiple mihomo versions
- Quick proxy testing and switching
- Custom automation scripts
- Automated testing with proxies
- Isolated test environments
- Version-specific testing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Install Rust (1.70+)
- Clone the repository
- Run tests:
cargo test - Run clippy:
cargo clippy - Format code:
cargo fmt
MIT License - see LICENSE for details.
- mihomo - Mihomo