User Manual
OrpheAgent Release Note
Version 1.0.8
OrpheAgent 1.0.8
Release Date: January 27, 2026
New Features
- No new features in this release.
Enhancements
- Port Listening Mutex Lock: Added a mutex lock mechanism in port listening functions to prevent concurrent access issues, improving system stability.
- UDP Hole Punch Logic Optimization: Improved the UDP Hole Punch mechanism to prevent race conditions that could cause it to malfunction.
- Relay Connection Exit Process: Optimized the relay connection exit process to avoid prolonged blocking during service shutdown.
Bug Fixes
- Low Latency Tunnel Mode Deadlock: Fixed an issue where the system could hang during the shutdown of the Data Plane process after switching to Low Latency Tunnel mode.
- Agent-to-Agent Tunnel IP Loop Issue: Resolved an issue where the Agent-to-Agent mechanism could get stuck in a loop while waiting for Tunnel IP configuration.
- Connection Instability: Fixed an issue where connections were incorrectly judged as invalid, causing constant switching between Direct, Relay, and Offline modes, leading to unstable connections.
- Exit Node Mode Issue: Fixed an issue where deleting an adjacent node in Exit Node mode did not properly disable the Route To Exit Node mode if it was set for that node.
- Deadlock in Set Status and Set Node Functions: Resolved a deadlock issue that caused the system to hang in the Set Status and Set Node functions.
- Offline Packet Dropping: Implemented a mechanism to drop packets when offline to prevent queue buildup and latency spikes upon connection recovery.
- HighThroughputFairSchedule Blocking: Fixed an issue where the HighThroughputFairSchedule mechanism caused the service to hang during shutdown.
OrpheAgent 1.0.7
Release Date: January 15, 2026
New Features
- No new features in this release.
Enhancements
- No enhancements in this release.
- Dial Timeout Optimization: Updated the dial timeout from 3 seconds to 15 seconds to improve peer connection reliability during hole punching and discovery processes.
- UDP Hole Punching Sensitivity Adjustment: Reduced detection sensitivity for UDP hole punching connection failures to minimize false positives in unstable network environments, providing nodes with more retry opportunities for successful hole punching under NAT/Firewall conditions.
Bug Fixes
- No bug fixes in this release.
OrpheAgent 1.0.6
Release Date: January 8, 2026
New Features
- Profile Management: Added Profile Management functionality allowing users to switch between Profiles to connect to different OrpheLink accounts.
- Profile CLI Command: Added
orphe-agent profilecommand for configuring and managing Profiles. - LuCI Profile Management Page: Added Profile Management settings page in the LuCI interface.
- Agent-to-Agent Control Module: Implemented Agent-to-Agent Control Module providing API Endpoints for LAN-to-LAN configuration, Exit Node configuration, and Route to Exit Node configuration. This module supports decentralized configuration where all operations and synchronization are completed between OrpheAgent nodes without OrpheLink involvement.
- Pending Task Mechanism: Added Pending Task mechanism to Agent-to-Agent Control Module, enabling configuration when devices are Offline and automatic application when devices come Online.
- Basic Config API: Added
POST /api/v1/config/basicAPI endpoint for setting Provision Key and Device name, reducing configuration wait time and improving operational fluency.
Enhancements
- Data Plane Status Protocol Values: Changed Protocol values in Data Plane Get Status API from
tcptoTCP TLS1.3andudptoQUIC. - Data Plane Status Quality Format: Unified Quality values to capitalized format (Good, Bad, Offline).
- Node Status OS Field: Added Device name and OS field to Node Status in Data Plane Get Status API to display node operating system.
- Data Plane Node API Enhancement: Added Device name and OS fields to
/api/v1/dataplane/nodeAPI response. - Controller Report OS Info: Added OS information to Report to Controller mechanism.
- Data Plane Power Optimization: Optimized Data Plane Forwarding code for significant power consumption reduction, greatly decreasing battery usage and extending device battery life.
Bug Fixes
- OpenWrt Firewall Rules: Fixed issue where Firewall rules may not be correctly added after executing Set Config on OpenWrt systems. This issue could cause exceptions when OrpheLink calls OrpheAgent API.
OrpheAgent 1.0.5
Release Date: December 19, 2025
New Features
- Data Plane Status WebSocket Endpoint: Added
GET /api/v1/dataplane/status/wsWebSocket endpoint to enable proactive notification of Data Plane status information. - Service Status WebSocket Endpoint: Added
GET /api/v1/service/status/wsWebSocket endpoint for proactive notification of OrpheAgent and OrpheLink connection status. - Service Toggle API: Added
GET/POST /api/v1/service/toggleAPI endpoint to enable switching Control Plane and Data Plane on and off. - P2P Quality Assessment: Enhanced Data Plane status information with P2P connection quality assessment mechanism and added functionality to retrieve OS and Device name information.
- Agent-to-Agent Communication: Implemented inter-Agent communication functionality allowing Agents to send control messages and share device-related information.
- mDNS Support for Data Plane: Added mDNS functionality to Data Plane, enabling P2P direct connection establishment in offline environments.
- Relay Transport for Low Latency Tunnel Mode: Implemented Relay Transport functionality support for Low Latency Tunnel mode.
- mdns Option for dp-p2p Command: Added
--mdns(-m) option to theorphe-agent dp-p2pcommand.
Enhancements
- Control Plane Relay Keep Alive Optimization: Optimized Control Plane Relay Keep Alive mechanism to further reduce processing time when Control Plane is in Disable state.
- Control Plane Status Sync: Enhanced status information synchronization when Control Plane is in Disable state, ensuring accurate and up-to-date status reporting.
- Status Command Output Clarity: Optimized
orphe-agent statuscommand output to be more clear and readable, improving user understanding of status information. - Tunnel Mode Short Option: Changed short option for tunnel mode from
-mto-tfor improved clarity. - LuCI UI Experience: Improved LuCI UI user experience for better usability and visual clarity.
Bug Fixes
- Data Plane Status Deadlock: Fixed potential deadlock issue in Data Plane during Get Status and Set Status operations.
- Endpoint IP Address Empty String: Fixed issue where Endpoint IP Address could be an empty string.
- CPU Temperature Display: Fixed abnormal CPU temperature display issue.
- go-ds-badger2 Library Assert Failed: Fixed potential issue where
github.com/ipfs/go-ds-badger2library could cause daemon restart due to Assert failed error.
OrpheAgent 1.0.4
Release Date: December 4, 2025
New Features
- System Information API: Added
GET /api/v1/system/infoAPI to retrieve software version and related information of OrpheAgent. - Route Subnet to Exit Node API: Added
POST /api/v1/dataplane/routesubnettoexitandGET /api/v1/dataplane/routesubnettoexitAPIs to support routing traffic for specified subnets and directing it to the Exit Node. - iptables MDNS Support: Added iptables rule to allow UDP traffic on port 5353, ensuring proper MDNS Discover functionality.
- Data Plane LAN to LAN & Route to Exit Routing Management: Implemented comprehensive routing management logic for Data Plane LAN to LAN and Route to Exit scenarios, with periodic checks to identify and compensate for missing entries in the routing table.
Enhancements
- UDP Hole Punch & Relay Optimization: Improved UDP Hole Punch and Relay mechanisms for both Control Plane and Data Plane, enhancing efficiency of direct and relay connection establishment and failover.
- P2P Network State Check: Strengthened P2P network state checking for Control Plane and Data Plane, providing more accurate connection status determination.
- Provision Process Efficiency: Enhanced the efficiency of the Provision workflow.
- Controller Offline Notification: After leaving the Controller, control messages are proactively sent via the Control Plane Tunnel to notify offline status, helping OrpheAgent clear related Control Plane P2P settings and reducing wait time for subsequent Provision executions.
- iptables Chain Name Consistency: Changed iptables chain name from "OrpheAgent" to uppercase "ORPHEAGENT" for improved consistency.
- Go Build Trimpath: Added
-trimpathflag to the go build command to prevent system path information from being included in output files. - SetNode Mutex: Added mutex to the SetNode function to ensure thread-safe access to shared resources and prevent race conditions.
Bug Fixes
- OrpheAgent Direct Connection: Fixed issue where two OrpheAgent instances could not establish direct connections when one OrpheAgent is running on the upstream router.
- Data Plane Disable Status Update: Fixed issue where status-related messages were not updated after disabling Data Plane.
- CPU Temperature Calculation: Fixed potential calculation error for CPU Temperature on devices with multiple temperature sensors.
- Firefox OrpheLink Auth Portal Redirect: Fixed issue where OrpheLink Auth Portal page could not properly redirect when using Firefox browser.
- Relay Transport Shutdown: Fixed issue where Control Plane could not properly shut down Relay Transport.
- Status Command Error: Fixed error when running
orphe-agent statuswithout connecting to Controller. - WebSocket Statistics Stability: Fixed potential errors in WebSocket
/api/v1/network/statistics/ws, improving system stability. - DHT Datastore Memory Leak: Fixed potential memory leak in DHT datastore function.
- Event Sender/Receiver Buffer Handling: Fixed issue where sending/receiving data larger than buffer limit could result in incomplete data reception.
- Data Plane Status Table Item Order: Fixed issue where Data Plane Status Table items could be reordered due to missing sorting mechanism.
OrpheAgent 1.0.3
Release Date: October 17, 2025
New Features
- Hole Punch Event WebSocket: Added WebSocket endpoint for real-time hole punching events. Handles WebSocket connections to provide live notifications about NAT traversal attempts, including address exchange, hole punch attempts, and connection status updates between peers.
- Data Plane P2P Control Commands: Enhanced
orphe-agent dp-p2pcommand with newupanddownactions for toggling the Data Plane on/off. - SNAT Support for Data Plane: Added
-s, --snatflag toorphe-agent dp-p2pcommand to enable Source NAT (SNAT) for data plane traffic. - LuCI Data Plane P2P Configuration Page: Added a new Data Plane P2P settings page in LuCI with equivalent functionality to the
orphe-agent dp-p2pcommand. The Data Plane Tunnel Mode configuration has been moved from the Config page to this new dedicated page.
Bug Fixes
- Fixed
orphe-agent downCommand Hang: Resolved issue where theorphe-agent downcommand would freeze/hang during execution. - Fixed OrpheAgent Toggle in LuCI: Resolved issue where enabling/disabling OrpheAgent through the LuCI interface would fail.
Enhancements
- Simplified Peer Discovery and Traversal: Streamlined the operation flow of both Decentralized Peer Discovery and Traversal mechanism and Centralized Relay-Assisted Traversal mechanism for improved performance and reliability.
- Removed Development Mode APIs: Removed
GET /api/v1/develop/modeandPOST /api/v1/develop/modeendpoints to prevent users from modifying the current mode through API calls, ensuring better system stability and security.
OrpheAgent 1.0.2
Release Date: October 3, 2025
New Features
- Data Plane P2P Management: Added new
dataplane-p2pcommand for configuring data plane peer-to-peer settings with actions to save, show, and clean configurations
Bug Fixes
- Provision Key Assignment: Fixed provision key assignment logic to ensure ProvisionKey is only assigned from existing configuration if not provided in input, preventing accidental overwriting with empty values and maintaining configuration integrity
- Control Plane P2P Flags: Fixed issue where
--udp-hole-punch,--mdns, and--relayflags incontrolplane-p2pcommand were not taking effect
Enhancements
- Command Naming Consistency: Renamed command from
control-plane-p2ptocontrolplane-p2pfor consistency - Data Plane Configuration Refactoring: Removed
dataplane-tun-modefromconfigcommand and added--tun-modeflag todataplane-p2pcommand - Thread Safety Improvements: Updated DHT datastore initialization to use
syncds.MutexWrapfor improved thread safety in both control plane and data plane P2P discover modules - Configuration Validation: Added checks for existing configuration ports before saving new settings with proper error logging when ports are unavailable
- Relay Discovery Improvements: If the number of relay nodes available for connection is zero, the Relay Discovery mechanism will be retried. Additionally, after successful provisioning, the settings for the Control Plane secure option will no longer be overwritten
- Documentation: Updated README.md with comprehensive Data Plane P2P Management and Config section including command usage, options, and examples
- OrpheConsole Improvements prevent enabling dataplane in orphe-console mode
OrpheAgent 1.0.1
Release Date: September 26, 2025
New Feature
- Firewall Management System: Introduced a comprehensive Firewall Management function that:
- Performs periodic comparisons between nftables and iptables rule states
- Automatically detects and repairs inconsistencies
- Ensures firewall configuration stability and reliability
- Provision Command for CLI: Added a new
provisioncommand to the CLI that:- Configures discovery settings including Multicast, MDNS, and Relay discovery mechanisms
- Supports three actions: save (configure settings), show (display current configuration), and clean (restore defaults)
- Provides granular control over device discovery protocols with boolean flags for each mechanism
- Includes automatic restart prompts to apply configuration changes seamlessly
Fix Bug
- Thread Safety Enhancement: Added mutex lock to the dataplane set status function to prevent panic conditions when multiple threads execute the function simultaneously
- Relay Address Validation: Implemented error handling for self-owned relay address format issues to prevent system panics
- Traffic Graph Corrections: Fixed negative value issues in Traffic Graph displays
- Status Command Fixes: Resolved status and traffic statistics anomalies in the
orphe-agent statuscommand
Enhancement
- Jump to Service Optimization: Streamlined Jump to Service functionality for both Cloud and On-Premises versions to improve performance and resource utilization
- Enhanced Dataplane IP Rule Priority: Elevated the priority of Dataplane IP rules to ensure proper rule application and prevent conflicts
- Improved Provision Mechanism: Strengthened the Relay Discovery process within the Provision mechanism, enhancing device discovery efficiency and stability
- Bootstrap Node Updates: Updated bootstrap node multi-address configuration for improved connectivity
- OrpheLink Connection State Protection: Added firewall rule to prevent end devices with OrpheAgent from connecting to OrpheLink, ensuring accurate OrpheLink connection state detection mechanism
