Handshaking
Secure Cluster Sync
Handshaking
Secure Cluster Sync
Official engineering documentation for the Brain & Muscle distributed task orchestration platform, targeting backend engineers and system administrators.
Muscle nodes are designed to run persistently in the background. They support two primary paradigms modes of execution.
The Muscle node operates strictly via outbound TCP on port 9000. Ensure that the host network (including Virtual Machine Network Security Groups) permits outbound traffic on this port. Note that standard ICMP (ping) traffic to the Brain is not required.
Foreground execution runs the binary directly in the active terminal session. This mode is exclusively used for local development, debugging, and temporary executions. Logs are streamed directly to stdout.
Linux / Ubuntu
macOS (Apple Silicon)
Windows
For production workloads, Muscle must execute as a background process completely isolated from active user sessions.
Create a unit file /etc/systemd/system/bam-muscle.service, then execute systemctl enable --now bam-muscle.service.
Create a .plist file in /Library/LaunchDaemons/com.bam.muscle.plist. Execute sudo launchctl load -w /Library/LaunchDaemons/com.bam.muscle.plist.
It installs itself natively as a Windows Service running in Session 0, ensuring complete isolation from interactive user sessions.
The Data Plane employs a "Thin Host" strategy. Execution occurs in a locked-down Docker runtime (GCC, Go, Python, or Node.js) across a strict three-phase lifecycle:
The Muscle validates the assigned task payload. It securely fetches Azure SAS tokens for artifact storage, clones the requisite code shards across branches, and executes any specified pre-flight operations dictated by gather_script_path.
The Muscle mounts the fetched code and datasets into the running container as isolated volumes. The core engine executes the designated user_script_path. Upon termination, the Muscle captures streams, synchronizes the final output directly to the cloud storage provider via the SAS token, and reports a terminal status back to the Brain.
To maintain strict statelessness and prevent host disk saturation, the Muscle forcefully destroys the isolated container and aggressively wipes all cloned repositories, temporary volumes, and local artifacts immediately after the SAS upload transaction completes.
Instead of complex DAGs (Directed Acyclic Graphs), Map-Reduce workloads are managed using a strict chunk index counter system. The Brain splits large processing tasks across the cluster, deploying independent MAP tasks linked by atomic slice indices. Once all chunk counters reach terminal success, the Brain natively executes the REDUCE phase logic to aggregate the distributed outputs securely.
Long-running web applications (APIs, Dashboards) are operated as Services. The Brain binds the executing code directly inside a continuously running Docker container (your configured codespace) and manages a native reverse proxy tunnel. This securely routes external HTTP requests directly to the bound port explicitly exposed by the Muscle executing the container.
For distributed machine learning training sequences, the platform utilizes a Parameter Server (PS) topology. Compute nodes pull neural network weights from the PS, calculate gradients locally against specific dataset shards, and push the gradients back. The Brain enforces a strict staleness bound (typically a staleness threshold of 2-3 batches) to balance rapid asynchronous mathematical computations against overall model convergence stability.
The Brain circumvents the limitations of standard OAuth proxies by operating as a fully native GitHub App.
Execute your workloads via the Next.js visual dashboard command center.
3.11). Verify your logic accepts streams.2.5 vCores).DATASET_PATH and target your application map scripts/mapper.py.To ensure high availability across long-term sustained cluster lifetimes, hosts operating long-living Muscle nodes must strictly undergo routine preventative maintenance sequences.
While Phase 3 TEARDOWN actively manages atomic task artifacts, residual images, log volumes, and abandoned processes will accumulate over months. It is imperative that system administrators schedule crontab / TaskScheduler sweeps enforcing system cleanups. You must periodically erase storage within:
Furthermore, ensure active system pruning is utilized via Cron (e.g. docker system prune -af --volumes) to eliminate isolated ghost container layers abandoned over months of heavy data-plane operations.
The Brain synthesizes your user dashboard requests into atomic JSON payloads. Muscles consume these raw manifests over the TCP control channel to allocate resources strictly overriding and enforcing required_cpu constraints and bootstrapping the GATHER and RUN workflows.
Explore the source code or report an anomaly directly to the terminal core.