RPyC Bridge Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The RPyC Bridge Architecture provides a mechanism for remote Python access to MetaTrader 5 (MT5) running within a Dockerized environment. Although the project has largely migrated towards a gRPC-based communication model for improved performance and asynchronous capabilities, it retains a standalone bridge component derived from mt5linux. This bridge facilitates communication between a host Python environment (which may be Linux or macOS) and the MT5 terminal, which must execute within a Windows-compatible Wine environment.
The architecture is designed to overcome the platform restrictions of the official MetaTrader5 Python package, which is natively limited to Windows. By hosting a service within the container that interacts directly with the MT5 terminal via Wine's Python, the bridge allows external clients to execute trading operations, retrieve market data, and monitor account status across network boundaries.
Sources: README.md:27-31, README.md:155-159, docker/container/metatrader/mt5.proto:3-4
Core Components and Deployment
The bridge architecture relies on a specific file structure and deployment process to ensure the gRPC/RPyC service can communicate with the MT5 terminal.
Bridge File Distribution
During the container setup, critical bridge files are moved into the Wine environment's Python site-packages directory. This ensures that when the bridge service starts, it has local access to the MT5 Python bindings and the necessary protocol stubs.
| File | Purpose |
|---|---|
bridge.py | The main service logic that wraps MT5 calls. |
mt5_pb2.py | Data structures generated from the gRPC protocol. |
mt5_pb2_grpc.py | Service definitions generated from the gRPC protocol. |
_generated_protocols.py | Typed runtime boundaries for bridge modules. |
Sources: docker/container/metatrader/setup.sh:317-331, docker/container/metatrader/_generated_protocols.py:1-5
Service Orchestration
The bridge is managed as an s6-overlay service (svc-mt5server). The startup sequence involves initializing the Wine prefix, installing the MT5 terminal, and then launching the bridge process. The bridge service is specifically configured to bind to port 8001 to allow external communication.
The diagram shows the sequence of events from container start to the operational state where the bridge acts as an intermediary.
Sources: docker/container/metatrader/setup.sh:374-406, tests/test_static.py:465-475, README.md:239-242
Protocol and Communication
The bridge utilizes gRPC to replace the original RPyC implementation for better performance. It defines a comprehensive service interface in mt5.proto that mirrors the official MetaTrader 5 Python API.
Interface Mapping
The bridge maps complex MT5 data types into gRPC-compatible messages. For instance, market data normally returned as numpy arrays is serialized into bytes within a NumpyArray message to facilitate cross-platform transfer.
message NumpyArray {
bytes data = 1; // numpy.tobytes()
string dtype = 2; // numpy dtype string
repeated int32 shape = 3;
}
Sources: docker/container/metatrader/mt5.proto:99-103
Supported Operations
The MT5Service definition includes RPC methods for all standard MT5 categories:
- Terminal Operations:
Initialize,Login,Version,LastError. - Account Information:
TerminalInfo,AccountInfo,GetProvisionedAccount. - Market Data:
CopyRatesFrom,CopyTicksRange,SymbolsGet. - Trading:
OrderSend,OrderCheck,PositionsGet.
Sources: docker/container/metatrader/mt5.proto:179-245
Recovery and Health Monitoring
A dedicated health_monitor.sh script runs in the background to ensure the bridge and MT5 terminal remain operational.
Auto-Recovery Logic
The health monitor periodically performs checks. If a failure threshold is met, it signals for a service restart via a RESTART_TOKEN. The svc-mt5server service monitors this token and performs a "full restart," which involves killing and restarting both the MT5 terminal and the bridge process.
This diagram illustrates the loop between monitoring and the recovery process initiated by the s6 service.
Sources: tests/test_static.py:440-455, tests/test_static.py:516-538, README.md:214-216
Integration with mt5linux
The bridge is designed to be compatible with the mt5linux library. External clients install mt5linux and connect to the bridge using the container's IP and port 8001.
Client-Side Usage
from mt5linux import MetaTrader5
# The bridge listens on port 8001 inside the container
mt5 = MetaTrader5(host='host-running-docker', port=8001)
mt5.initialize()
print(mt5.version())
Sources: README.md:162-167
Array Handling in RPyC 6.x
While the project has moved toward gRPC, README.md notes that for legacy RPyC usage (if applicable), RPyC 6.x security settings require the use of rpyc.classic.obtain() to handle numpy arrays, as direct access to __array__ is blocked.
Sources: README.md:183-188
Summary
The RPyC Bridge Architecture (now primarily implemented via gRPC) provides a stable, cross-platform interface for MetaTrader 5. By isolating the Windows-dependent MT5 environment inside a Docker container and exposing a standardized service via port 8001, the architecture enables robust, remote algorithmic trading and data analysis from native Linux and macOS environments. The system is bolstered by s6-overlay management and proactive health monitoring to ensure high availability.
Sources: README.md:27-40, docker/container/metatrader/mt5.proto:3-5