This report evaluates how to transform the current NodeShare proof-of-concept into a production-grade, multi-node, secure distributed computing platform. By identifying and adapting established architectures, algorithms, and interfaces from mature open-source projects, we can dramatically minimize development time while preserving codebase maintainability.
The current implementation of NodeShare is a point-to-point (1-to-1) remote command execution system. It establishes a direct, interactive session between two specific actors:
- Provider (Worker): Serves incoming connection requests, collects local hardware specs, receives directories of code over the wire, builds Docker images locally, runs them using a
Makefileharness, and streams output back to the client. - Requester (Client): Initiates connections, drives the provider through an interactive REPL terminal, uploads local directories, triggers task execution, and displays streaming logs.
sequenceDiagram
autonumber
actor Requester
actor Provider
Note over Requester, Provider: 1-to-1 Connection over libp2p
Requester->>Provider: Handshake (Noise + Yamux)
Provider->>Requester: Handshake Response
Requester->>Provider: Exchange SystemInfo (gopsutil telemetry)
Provider->>Requester: Exchange SystemInfo Response
Requester->>Provider: Ping (Initial Latency Check)
Provider->>Requester: Pong Response
Note over Requester, Provider: Interactive Terminal (REPL) Session Opened
Requester->>Provider: create-task (TaskTransferRequest + FileChunks)
Provider->>Provider: Save files to /tmp/nodeshare/tasks/<id>
Provider->>Requester: Transfer Ack (TerminalResponse)
Requester->>Provider: run-task
Provider->>Provider: Exec: docker build -t nodeshare-<id> <dir>
Provider->>Provider: Exec: docker run --name nodeshare-<id>-run nodeshare-<id> make
Provider-->>Requester: Stream LogUpdates (live stdout/stderr)
Provider->>Requester: TaskCompletion Message
- Networking Stack: Built directly on
go-libp2p. It uses TCP and QUIC-v1 for transport, Noise for end-to-end encryption, and Yamux for stream multiplexing. - NAT Traversal: Leverages UPnP/NAT-PMP port mapping, DCUtR (Direct Connection Utility for Routing) for active UDP hole punching, and public IPFS bootstrap nodes acting as Circuit Relay v2 hops. A secondary SSH-based tunnel via
Pinggyacts as a zero-config fallback. - Messaging Protocol: Structured as length-prefixed Protobuf envelopes (
proto/nodeshare.proto). It handles session setup, interactive commands, chunked directory transfers, stdout/stderr log streaming, and exit signals. - State Management: Ephemeral and thread-safe. A simple memory-bound registry (
internal/store/store.go) tracks connected peers, system specs, and latencies. No distributed database or persistent disk storage is utilized, save for the local private key (~/.nodeshare/identity.key). - Task Execution: Out-of-process execution via Go's
os/execcommand namespace. The provider invokes the local host'sdockerdaemon to build and run code, monitoring the socket for connection drops to kill orphan runs.
NodeShare is presently a remote execution engine rather than a true cluster scheduler. To reach the final vision of a production distributed computing platform, the following subsystems must be introduced:
- Automated Peer Discovery: Elimination of manual address sharing in favor of decentralized, self-healing routing tables (e.g., Kademlia DHT).
- Distributed Scheduling & Matchmaking: A mechanism to submit tasks to a network coordinator rather than a single peer, routing workloads based on cost, load, latency, and resource fit.
- Isolated Sandboxing (Secure Multi-Tenancy): Protecting providers from malicious workloads by wrapping runs in microVMs (e.g., Firecracker) or syscall-intercepting runtimes (e.g., gVisor) instead of default Docker.
- Hardware Passthrough & Virtualization: Automatic detection of CUDA/ROCm runtimes and GPU hardware, exposing fractional GPUs or partition slices to tasks.
- Consensus & Shared State: Replicated storage for job queues, worker health, and task states to eliminate single points of failure.
- Distributed Storage & Data Locality: A clustered storage layout allowing workers to fetch large datasets or input volumes without re-uploading them over slow client uplinks.
To achieve a production-grade decentralized platform, NodeShare must be decomposed into the following core, decoupled subsystems:
graph TD
subgraph Client Interface
CLI[NodeShare CLI]
API[gRPC / REST API]
end
subgraph Control Plane [Coordinators / Orchestrators]
Consensus[Raft State Replication]
Scheduler[Distributed Task Scheduler]
StateStore[Cluster State Store]
Queue[Distributed Task Queue]
end
subgraph Network Layer
DHT[Kademlia DHT / Routing]
Gossip[Gossipsub / State Broadcast]
NAT[Circuit Relay + DCUtR]
end
subgraph Compute Plane [Workers / Providers]
WorkerAgent[Worker Daemon]
CapTracker[NVML GPU & CPU Resource Tracker]
Executor[Execution Engine Manager]
end
subgraph Execution Runtimes
DockerRuntime[Docker / Containerd]
gVisorRuntime[gVisor Sandboxed Runtime]
FirecrackerVM[Firecracker MicroVMs]
WasmEngine[Wasmtime Engine]
end
subgraph Storage Layer
SharedFS[Distributed FS / SeaweedFS / IPFS]
end
%% Connections
CLI --> API
API --> Queue
Queue --> Scheduler
Scheduler --> StateStore
Consensus --> StateStore
Scheduler -.-> DHT
WorkerAgent -.-> DHT
WorkerAgent --> CapTracker
WorkerAgent --> Executor
Executor --> DockerRuntime
Executor --> gVisorRuntime
Executor --> FirecrackerVM
Executor --> WasmEngine
WorkerAgent --> SharedFS
- P2P Transport & Membership Routing: Handles network membership, Kademlia DHT routing, and gossip protocols (Gossipsub) for fast, low-overhead peer capability advertising.
- Consensus & Cluster Database: Establishes a replicated log (Raft) across orchestrator nodes to guarantee consistent state for task assignments, scheduling queues, and peer leases.
- Task Orchestrator & Multi-Node Scheduler: Matches incoming jobs to optimal workers by factoring in CPU core limits, memory capacity, latency constraints, and GPU requirements.
- Compute Node Agent: Local daemon running on provider hosts. It tracks local resource exhaustion, schedules tasks onto local runtimes, and monitors sandboxed processes.
- Secure Execution Sandbox: Wraps tasks in secure environments, utilizing gVisor's syscall interception or Firecracker's microVM hypervisor to prevent host compromise.
- GPU Detection & Slice Virtualization: Discovers physical NVIDIA/AMD GPUs via NVML or ROCm, allocating specific CUDA devices or fractions of vRAM to workloads.
- Distributed Storage System: Mounts shared input volumes on compute nodes dynamically, relying on content-addressable storage (like IPFS) or high-performance file layouts (like SeaweedFS) to optimize data locality.
- AAA Security & Access Control: Cryptographic identity validation, decentralized lease management, and token-based client authorizations.
To avoid rewriting these complex components, we catalog the highest-quality open-source projects whose codebases can be studied, adapted, or directly imported.
- URL: github.com/bacalhau-project/bacalhau
- Language: Go
- License: Apache License 2.0
- Stars: ~4,500
- Status: Active, backed by Expanso.
- Production Usage: Heavily used in production decentralized compute over data networks.
- Architecture Summary: Features a clean separation between Requester Nodes (orchestrators running the scheduler and tracking global state) and Compute Nodes (running task engines). Uses a pluggable executor layer (Docker, WASM) and storage drivers (IPFS, S3, HTTP).
- Key Source Files:
pkg/compute/capacity/tracker.go: Computes and enforces local node resources.pkg/executor/docker/executor.go: Controls the lifecycle of Docker containers.pkg/orchestrator/selection/matchmaker.go: Node selection logic for jobs.
- Maturity / Complexity: High maturity; high complexity.
- Integration Suitability: High. Bacalhau's architecture directly models NodeShare's goal. Its resource tracking and scheduling interfaces can be adapted into NodeShare's internal directories.
- URL: github.com/hashicorp/nomad
- Language: Go
- License: Business Source License (BSL) 1.1 (Note: Copying raw code raises legal hurdles; restrict to studying interfaces and design patterns).
- Stars: ~16,500
- Status: Active, corporate-backed.
- Production Usage: Industry standard for orchestration across major production clouds.
- Architecture Summary: Runs agent instances in either client or server modes. Servers handle consensus via Raft and execute scheduling algorithms. Clients run drivers (exec, Docker, QEMU) to manage isolation.
- Key Source Files:
client/driver/driver.go: Defines the core interface for execution runtimes.nomad/structs/structs.go: Structs mapping resource requests (CPU, memory, IO, networks).
- Maturity / Complexity: Extremely high; very high complexity.
- Integration Suitability: Low code reuse due to BSL 1.1 license restrictions, but highly valuable for studying job definition schemas and clean execution driver boundaries.
- URL: github.com/hashicorp/memberlist
- Language: Go
- License: MPL-2.0
- Stars: ~4,900
- Status: Actively maintained.
- Production Usage: Powering service discovery and heartbeats in Consul, Nomad, and Vault.
- Architecture Summary: Implements a gossip-based membership protocol using SWIM. Nodes broadcast metadata and discover peer joins/leaves.
- Key Source Files:
memberlist.go: Main library entry point managing membership loops.delegate.go: Interfaces used to broadcast custom metadata over gossip.
- Maturity / Complexity: Very high maturity; medium complexity.
- Integration Suitability: High. Can be imported directly as a Go library to handle decentralized peer heartbeats and node lists.
- URL: github.com/hashicorp/raft
- Language: Go
- License: MPL-2.0
- Stars: ~7,400
- Status: Highly maintained.
- Production Usage: The consensus backbone for Consul, Nomad, and various clustered databases.
- Architecture Summary: A Go library implementing the Raft consensus algorithm. Manages state machine replication, leader elections, and write serialization.
- Key Source Files:
raft.go: Core execution loop for Raft state machines.fsm.go: Finite State Machine interface for applying replicated commands.
- Maturity / Complexity: Extremely high maturity; high complexity.
- Integration Suitability: High. Can be imported as a dependency for maintaining coordinator cluster state, preventing conflicts in task allocation.
- URL: github.com/NVIDIA/go-nvml
- Language: Go
- License: Apache License 2.0
- Stars: ~550
- Status: Active, official NVIDIA bindings.
- Production Usage: Standard library powering Kubernetes GPU device plugins.
- Architecture Summary: Direct bindings to the NVIDIA Management Library (
libnvidia-ml.so) using cgo wrappers. - Key Source Files:
pkg/nvml/api.go: Exposes Go interfaces mapping to NVML functions.pkg/nvml/lib.go: Cgo linking logic.
- Maturity / Complexity: High maturity; low code complexity.
- Integration Suitability: High. Import as a Go module to allow compute nodes to automatically detect host GPUs and report available vRAM.
- URL: github.com/bytecodealliance/wasmtime-go
- Language: Go (wrapping Rust core via Cgo)
- License: Apache License 2.0
- Stars: ~950
- Status: Highly active.
- Production Usage: Cloudflare, Fastly, and edge runtimes.
- Architecture Summary: Safe Go API wrapping the high-performance Wasmtime WebAssembly compiler and execution engine.
- Key Source Files:
config.go: Configures memory limits, CPU quotas, and sandbox restrictions.linker.go: Maps host APIs into the Wasm sandbox guest.
- Maturity / Complexity: High; medium wrapper complexity.
- Integration Suitability: High. Excellent for introducing an ultra-lightweight execution runtime that runs directly inside the NodeShare process without container overhead.
- URL: github.com/google/gvisor
- Language: Go
- License: Apache License 2.0
- Stars: ~15,800
- Status: Active, backed by Google.
- Production Usage: Underpins Google Cloud Run, App Engine, and GKE Sandboxed Containers.
- Architecture Summary: Implements a user-space kernel (Sentry) written in Go that intercepts Linux system calls, isolating the host kernel from container processes.
- Key Source Files:
runsc/cli/main.go: The CLI entry point mimicking standard OCI runtime parameters.
- Maturity / Complexity: Production-grade; extremely high code complexity.
- Integration Suitability: Direct integration of the codebase is impractical due to complexity. However, we can use it externally: NodeShare can invoke Docker using the
--runtime=runscflag to execute untrusted code in a gVisor sandbox.
- URL: github.com/chrislusf/seaweedfs
- Language: Go
- License: Apache License 2.0
- Stars: ~19,800
- Status: Active.
- Production Usage: Clustered storage environments handling billions of files.
- Architecture Summary: High-performance, concurrent distributed file system. Combines a master server for metadata management with volume servers for file storage.
- Key Source Files:
weed/filer/filer.go: Manages file metadata and mount paths.
- Maturity / Complexity: High maturity; very high complexity.
- Integration Suitability: High. Used as a cluster storage backend. Workers mount SeaweedFS mounts dynamically to access input data without downloading full folders.
This section isolates specific components from the cataloged projects, describing exactly how they should be imported, adapted, or studied.
- Source Project: Bacalhau
- Target Files:
pkg/compute/capacity/tracker.go,pkg/compute/capacity/system/provider.go - Purpose: Tracks host CPU cores, RAM, and disk utilization, validating if incoming tasks fit within available limits.
- Reuse Strategy: Adapt Logic. Study the capacity provider implementation and write a simplified
internal/resource/tracker.goin NodeShare. - Reasoning: Bacalhau relies on an extensive network configuration model. Adapting its logic allows us to write a lightweight struct matching our Protobuf schema while discarding irrelevant config paths.
- Required Modifications: Map the returned metrics directly to fields in
gen.SystemInfo(CPU, memory, disk). - Dependencies:
github.com/shirou/gopsutil/v3. - Effort / Risk: 3 days / Low.
- Source Project: NVIDIA go-nvml
- Target Files:
pkg/nvml/api.go,pkg/nvml/consts.go - Purpose: Detects host-level GPU counts, names, memory, and CUDA versions.
- Reuse Strategy: Direct Import. Import
github.com/NVIDIA/go-nvmlas a standard dependency ingo.mod. - Reasoning: Writing custom NVML bindings is highly error-prone. The official library is stable and Apache-2.0 licensed.
- Required Modifications: None. We will invoke the NVML functions inside our
sysinfopackage:// In internal/sysinfo/sysinfo.go import "github.com/NVIDIA/go-nvml/pkg/nvml" func AddGPUMetrics(info *gen.SystemInfo) { if nvml.Init() == nvml.SUCCESS { defer nvml.Shutdown() count, _ := nvml.DeviceGetCount() info.Capabilities = append(info.Capabilities, fmt.Sprintf("gpu-count:%d", count)) } }
- Dependencies: Requires target host to have the NVIDIA driver library installed.
- Effort / Risk: 1 day / Low.
- Source Project: go-libp2p-kad-dht
- Target Files:
github.com/libp2p/go-libp2p-kad-dht(Full Package) - Purpose: Peer discovery using Kademlia DHT routing tables.
- Reuse Strategy: Direct Import. Import the package to create a DHT instance alongside our host construct in
internal/host/host.go. - Reasoning: The standard way to resolve address coordinates without a centralized coordinator.
- Required Modifications: Integrate DHT bootsrapping inside our host initialization:
// In internal/host/host.go import dht "github.com/libp2p/go-libp2p-kad-dht" func NewDHT(ctx context.Context, h host.Host) (*dht.IpfsDHT, error) { return dht.New(ctx, h, dht.Mode(dht.ModeServer)) }
- Dependencies:
github.com/libp2p/go-libp2p. - Effort / Risk: 4 days / Medium (DHT bootstrap syncs can occasionally stall on poor connections).
- Source Project: HashiCorp Nomad
- Target Files:
client/driver/driver.go - Purpose: Abstracting runtime environments (Docker, Firecracker, WASM) under a clean Go interface.
- Reuse Strategy: Copy and Clean Interface. Copy the core driver interface signatures (e.g.,
StartTask,StopTask,Stats) and define them in a new packageinternal/executor/driver.go. - Reasoning: Restructuring execution as pluggable drivers keeps NodeShare's core daemon isolated from the specific runtime version in use.
- Required Modifications: Strip Nomad's job-tracking metrics and logging wrappers, keeping only the execution parameters (task ID, path, resource constraints).
- Dependencies: None.
- Effort / Risk: 4 days / Low.
This roadmap structures development from NodeShare's 1-to-1 CLI to a complete multi-node cluster.
gantt
title NodeShare Acceleration Roadmap
dateFormat YYYY-MM-DD
section Milestone 1
Decentralized Discovery :active, m1, 2026-06-25, 6d
section Milestone 2
GPU & Resource Trackers : m2, after m1, 4d
section Milestone 3
Consensus & Orchestration : m3, after m2, 10d
section Milestone 4
Secure Sandbox Engines : m4, after m3, 7d
section Milestone 5
Data Locality & Volumes : m5, after m4, 8d
- Feature: Nodes automatically discover peers on the local LAN or WAN, maintaining a dynamic cluster map without manual multiaddr sharing.
- Recommended Repositories:
libp2p/go-libp2p-kad-dhtandhashicorp/memberlist. - Implementation Steps:
- Import
go-libp2p-kad-dhtinsideinternal/host/host.go. - Start a background discovery routine using libp2p routing advertisements.
- Integrate
memberlistfor sub-second failure detection and heartbeats.
- Import
- Files to Study:
pkg/discoveryin Bacalhau;memberlist.goin memberlist. - Estimated Effort / Risk: 6 days / Low.
- Outcome: Running
nodeshare startautomatically hooks the node into the local DHT ring.
- Feature: Workers parse their host limits (CPUs, available memory, disk, NVIDIA GPUs) and advertise these in their
SystemInfopayloads. - Recommended Repositories:
NVIDIA/go-nvmlandshirou/gopsutil. - Implementation Steps:
- Add
NVIDIA/go-nvmlto imports. - Update
internal/sysinfo/sysinfo.goto scan GPU core/vRAM metrics. - Define resource limit types in
proto/nodeshare.protoand regenerate Protobuf bindings.
- Add
- Files to Study:
pkg/compute/capacity/system/provider.goin Bacalhau. - Estimated Effort / Risk: 4 days / Low.
- Outcome: Requesters can query active worker capabilities and inspect GPU stats via
sysinfo.
- Feature: Introducing Coordinator nodes that maintain a Raft log to orchestrate job queues, leasing tasks to workers based on capacity.
- Recommended Repositories:
hashicorp/raftandbacalhau-project/bacalhau. - Implementation Steps:
- Create a
nodeshare coordinatorsubcommand. - Initialize
hashicorp/raftacross coordinator instances. - Adapt Bacalhau's matchmaking logic (
pkg/orchestrator/selection/matchmaker.go) to route queue tasks to matching workers.
- Create a
- Files to Avoid: Nomad's scheduler packages (due to BSL 1.1 licensing).
- Estimated Effort / Risk: 10 days / High (Distributed state machines require extensive validation).
- Outcome: Jobs submitted to the cluster are queued, scheduled, and rescheduled if a worker drops.
- Feature: Isolating executing tasks in user-space runtimes to prevent security compromises of provider hosts.
- Recommended Repositories:
google/gvisorandbytecodealliance/wasmtime-go. - Implementation Steps:
- Expose runtime selection flags (
docker,gvisor,wasm) in task configurations. - In the local executor, if
gvisoris set, invoke the Docker API withRuntime: "runsc". - Implement a WebAssembly execution driver using Wasmtime Go.
- Expose runtime selection flags (
- Estimated Effort / Risk: 7 days / Medium.
- Outcome: Malicious code cannot compromise the provider, running safely in a restricted microkernel or Wasm sandbox.
- Feature: Tasks mount network volumes dynamically, minimizing upload requirements for large model checkpoints or training sets.
- Recommended Repositories:
chrislusf/seaweedfsandjuicedata/juicefs. - Implementation Steps:
- Integrate SeaweedFS mount helper scripts on workers.
- Map input volumes directly inside sandboxed runtimes.
- Estimated Effort / Risk: 8 days / Medium.
- Outcome: Workers mount multi-gigabyte training files in milliseconds from a local caching node, boosting network efficiency.
This reference table maps every NodeShare target feature to its open-source reference implementations, defining reuse methods and difficulty levels.
| NodeShare Feature | Target Repository | GitHub Reference Link | Reusable Files / Packages | Reuse Strategy | Difficulty | Priority |
|---|---|---|---|---|---|---|
| GPU Scheduling | Bacalhau | bacalhau-project/bacalhau | pkg/compute/capacity/ |
Adapt Logic | Medium | High |
| GPU Telemetry | NVIDIA go-nvml | NVIDIA/go-nvml | pkg/nvml/ |
Direct Library | Low | High |
| P2P Discovery | Libp2p DHT | go-libp2p-kad-dht | Full Package | Direct Library | Medium | Critical |
| Node Heartbeats | Memberlist | hashicorp/memberlist | memberlist.go, delegate.go |
Direct Library | Low | High |
| State Replication | HashiCorp Raft | hashicorp/raft | raft.go, fsm.go |
Direct Library | High | High |
| Docker Driver | Nomad | hashicorp/nomad | client/driver/docker/ |
Adapt Interfaces | Medium | Critical |
| WASM Execution | Wasmtime Go | wasmtime-go | wasmtime/ |
Direct Library | Low | Medium |
| gVisor Sandboxing | gVisor | google/gvisor | runsc/ |
External runtime | Low | Medium |
| Distributed storage | SeaweedFS | chrislusf/seaweedfs | weed/filer/ |
External mount | Medium | Low |
While these repositories accelerate development, some systems unique to NodeShare's peer-to-peer sharing model must be written from scratch:
- Decentralized Access Leases: A cryptographically signed lease system verifying client credit limits or tokens before permitting tasks.
- Reference pattern: Studied from Akash Network (
github.com/akash-network/node- Cosmos SDK lease agreements).
- Reference pattern: Studied from Akash Network (
- Reputation & Scoring: Workers must rate requesters on payload behaviors (e.g., resource exhaustion), while clients must rate workers on performance stability.
- Reference pattern: Studied from IPFS Bitswap ledger scoring (
github.com/ipfs/go-libipfs/bitswap/decision).
- Reference pattern: Studied from IPFS Bitswap ledger scoring (
- Local Resource Slicing: Dynamically restricting network bandwidth and CPU shares on worker hosts during task execution.
- Reference pattern: Studied from cgroups v2 configurations in Go (
github.com/containerd/cgroups).
- Reference pattern: Studied from cgroups v2 configurations in Go (
When copying or adapting code from these repositories, NodeShare must strictly comply with the following open-source licenses:
- Apache 2.0 (Bacalhau, NVML, gVisor, Wasmtime, SeaweedFS): Very permissive. We can copy, modify, and distribute code without licensing issues, provided we retain the original copyright notices and file headers.
- MIT / BSD (libp2p): Extremely permissive. Free to copy and reuse with attribution.
- MPL-2.0 (HashiCorp memberlist & raft): Weak copyleft. We can import these packages as libraries without modifying our own license. If we directly modify files inside
memberlistorraftthemselves, we must publish those modifications under the MPL-2.0 license. - BSL 1.1 (HashiCorp Nomad & late Consul): CRITICAL RISK. We must NOT copy-paste any source files from Nomad directly. We can only study their design patterns and re-implement the logic independently to avoid copyright infringement.
To build the platform as quickly as possible, we should proceed in this order:
- Integrate Peer Discovery: Use
go-libp2p-kad-dhtto remove the requirement for pasting connection strings. - GPU Telemetry: Integrate
NVIDIA/go-nvmlinto oursysinfocollector. - Pluggable Execution: Abstract our Docker code into a driver interface, opening the door for WASM and sandboxed containers.