hyperrcompute

🧠 hyperrcompute

hyperrcompute is a peer-to-peer remote compute execution platform designed to deploy lightweight, ephemeral Docker containers over a decentralized network using hyperdht. It allows clients to connect using a secure connection string and interact with isolated compute environments in real-time.

🚀 Features

• 🔐 Secure private connection strings (like SSH keys)
• 🐳 Ephemeral Docker containers (e.g. Ubuntu)
• 🌐 Web UI over TCP tunnels (via hyperdht)
• ⏱️ Configurable lifetime (--time) for each container
• 💥 Forceful spin-up even if another is running (--force)
• 🧪 Live mode with real-time data stream (--live)
• 🔐 To generate new server key use (--new)

📦 Installation

Install globally using npm:

npm install -g hyperrcompute@latest

OR

npm install -g hyperrcompute@0.0.12

⚠️ You may see a warning like:
npm WARN deprecated node-domexception@1.0.0: Use your platform's native DOMException instead
This is safe to ignore.

🧑‍💻 How to share GPU

Spin up a container on the provider:

hyperrcompute --image <DOCKER_IMAGE> --hours <HOURS>  --minutes <MINUTES> --force --live --connector <PRIVATE_CONNECTION_STRING>

Example:

  hyperrcompute --image ubuntu  --hours 1 --minutes 0 --force --live --connector 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062

  hyperrcompute --image ubuntu  --hours 1 --minutes 0 --force --live --connector 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062 --new

Expected output:

[INFO] Generated token: 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062
Starting server...
Docker Management Server running on port 3000.
ubuntu gpu-container-1751676124958
Creating container 'gpu-container-1751676124958' with image 'ubuntu'...
Container 'gpu-container-1751676124958' not found.
Pulling image 'ubuntu', this may take a moment...
Image 'ubuntu' pulled successfully.
Assigning port 8001 to container 'gpu-container-1751676124958'...
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|                                                                                                                       │
|                                                                                                                       │
|                                          Hyperrcompute TCP Server Started ⛵️                                          │
|                                      Connection Mode: Private Connection String                                       │
|                                   Hyperrcompute is now listening on 127.0.0.1:3000                                    │
|                    Connection string: 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062                    │
|   NOTE: TREAT PRIVATE CONNECTION STRINGS HOW YOU WOULD TREAT SSH KEY, DO NOT SHARE IT WITH ANYONE YOU DO NOT TRUST    │
|                                                                                                                       │
|                                                                                                                       │
|                                                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
OR Scan the QR to connect: 
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄▄███▀ ███ ▄▄█▄  █ ▄▄▄▄▄ █
█ █   █ █ ▀█ ▄▄█ ▀▀▀█ ███▀█ █   █ █
█ █▄▄▄█ █▄ ▄▄▀▄ ▄▀ ▄ ▄▀▄█ █ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄▀▄▀ █▄▀▄█▄█ █▄█▄▄▄▄▄▄▄█
█▄▄▄▄▀▀▄▀ ▀███▄▄██▄█ ▄  ▀ ▄▀█▄▄ ▀ █
█ █▄▄▄▀▄████▀▀▀ █▄█▄▀▀█▀    ▄▀██▀▄█
██  ██ ▄█▀ ▀ █▀█ ▀ █▀ █▄██▀█ ▄ ▀▄██
█ ▄▀█ ▄▄▀█▄▄█ ▀▄▀▀▄█ ▀▀ ▀ ██ ▄▄▀█▀█
█▀▄██  ▄ ▀ ▀▄▀▀█▀██▀██ █ ▄  ▀ █   █
██▀ █▄█▄ █ █▄ ██ ▀ ▄█▀▄▀▀███▄▄ ▄ ▀█
█  ▄▄▄█▄█ ▀▄▄  ▀█ ▄█▀▄ █▀█ ▀ █▄▄  █
██▀  ▄█▄▄ ▄ ▄▄▄██▄▄▄█ █▄ █▄▄▀▀▄█▀▄█
█▄█▄███▄▄▀▀█▀ █  ▀ █▀██▀▀ ▄▄▄  █▀▄█
█ ▄▄▄▄▄ ██▄  █▄▀████▄█ █  █▄█ █▀▄██
█ █   █ █▀▄ █▄█ ▀ █▄▄█▄ ▄▄▄▄▄▄█▄▄▀█
█ █▄▄▄█ █ █▀▀█  ▄ ▀ █▀▄▀  █ ▀▀▄██▀█
█▄▄▄▄▄▄▄█▄█▄██▄▄█▄▄▄▄▄▄▄▄██▄█▄█▄███

Container 'gpu-container-1751676124958' started successfully on port 8001.
[SUCCESS] Container started: Container 'gpu-container-1751676124958' started on port 8001: e472143fed55ea68b97e792d05208a9d3ad2390e39f6cefc5a620282c5054142
GPU added successfully
[INFO] Received valid response, starting Docker container...
[INFO] Container started with ID: e472143fed55ea68b97e792d05208a9d3ad2390e39f6cefc5a620282c5054142
[INFO] Server started
1 0 hours and minutes
[INFO] Timer started. Server will shut down in 3600 seconds.

🖥️ How to connect

To connect with the gpu we have to use below commands:

hyperrcompute --connect <PRIVATE_CONNECTION_STRING> --port <PORT>

Example:

  hyperrcompute --connect "89fd199803cd2aaf4b5cdba373a970a9e6a08f86547fee062-SPLIT-12cd30614bffe9e86eefeb7753e3f5245b06bc4bd906b63af" --port 3002

You’ll see output like:

Connecting to server...
Connection Key: 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062
Container ID: 12cd30614bffeef81b3efad784789e86eefeb7753e3f5245b06bc4bd906b63af
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|                                                                                                                                       │
|                                                                                                                                       │
|                                                  Hyperrcompute TCP Client Started ⛵️                                                  │
|                                              Connection Mode: Private Connection String                                               │
|Access application on http://localhost:5174/hyperrcompute/terminal?key=12cd30614bffeef81b3efad784789e86eefeb7753e3f5245b06bc4bd906b63af│
|                            Connection string: 89fd199803cd2aaf4b5cdba373a970a9e6a08f86547f26c24aae3efee062                            │
|             NOTE: TREAT PRIVATE CONNECTION STRINGS HOW YOU WOULD TREAT SSH KEY, DO NOT SHARE IT WITH ANYONE YOU DO NOT TRUST          │
|                                                                                                                                       │
|                                                                                                                                       │
|                                                                                                                                       │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
http://localhost:5174/hyperrcompute/terminal?key=12cd30614bffeef81b3efad784789e86eefeb7753e3f5245b06bc4bd906b63af

Open the link in browser to access terminal.

📁 .env Configuration

The .env file is auto-generated and stores:

• SERVER_KEY – required for authentication between peer nodes

📜 Logs & Tokens

During container execution, you’ll receive:

• 🔑 SERVER_KEY
• 🪙 JWT token for session
• 🐳 Docker management server port
• 🌐 Tunnel access URL (http://127.0.0.1:<PORT>)

🧯 Troubleshooting

• ReferenceError: containerId is not defined
  Ensure the container was started before referencing the ID. Likely a bug in demo-index.js.

• Docker must be running
  Start the Docker daemon before launching containers.

• Connection timeout
  Make sure provider is live and accessible via the correct private connection string.

🧪 Developer Usage

To test manually:

  node demo-index.js --new --image <IMAGE>  --hours <HOURS> --minutes <MINUTES> --force --live --connector <PRIVATE_CONNECTION_STRING>

🔐 Security

• Treat your private connection strings like SSH keys.
• Do not share them publicly.
• Always rotate keys periodically in production environments.

🤝 Credits

Built with ❤️ by the Hypercompute team.
Powered by Docker, Node.js, and peer-to-peer networking.

📃 License

MIT License.