Complete API Reference

ClusterNode, GuardProxy, and MemoryPool — Python & Node.js ESM

ClusterNode (symmetric master/worker binary)

MethodSignatureReturnsDescription
ClusterNode.__init__(role: str = 'auto', port: int = 29500, memory_budget_mb: int = 0, auth_secret: str = '', guard_band_mb: int = 300)—role is 'master', 'worker', or 'auto' (auto-detects based on whether a master is reachable). memory_budget_mb = 0 means use all available LPDDR minus guard_band_mb.
.start() → None—Binds the TCP listener (master) or connects to the master (worker) and begins memory-pool registration.
.stop() → None—Gracefully deregisters from the pool and closes all TCP connections.
.get_status() → dict{"role": str, "pool_mb": int, "workers": int, "failover_active": bool}Returns current pool state. failover_active is True when at least one worker has disconnected and UFS flash mmap streaming is active.
.read_tensor(offset_mb: float, size_mb: float) → bytesbytesFetches a contiguous tensor shard from the disaggregated memory pool. Transparently falls over to local flash if the responsible worker is offline.

ClusterConfig

FieldTypeDefaultDescription
rolestr'auto'Node role: 'master' | 'worker' | 'auto'.
portint29500TCP port for master–worker communication.
memory_budget_mbint0Maximum LPDDR to donate. 0 = all available minus guard-band.
guard_band_mbint300Reserved memory headroom to prevent Android LMK kills on the worker node.
auth_secretstr''Shared HMAC-SHA256 secret for GuardProxy authentication. Empty string disables auth (development only).
failover_pathstr'/data/data/com.termux/files/home/cluster_swap'Local UFS path used for flash-backed storage-assisted failover when a worker disconnects.

GuardProxy

MethodSignatureReturnsDescription
GuardProxy.__init__(secret: str, fail_fast_ms: float = 1.0)—Creates an HMAC-SHA256 guard proxy. Connections failing verification within fail_fast_ms are rejected immediately.
.verify(token: str, payload: bytes) → boolboolVerifies an incoming HMAC token against the payload. Returns False on mismatch; does not raise.
.sign(payload: bytes) → strstrProduces an HMAC-SHA256 hex token for an outgoing payload.