Skip to main content

Mount and Module

This chapter walks you through how to connect your custom-built virtual machine (VM) to the HyMatrix node and network. You will learn how to:

  • Install and use the hymx toolkit locally
  • Mount your VM to a local development node for testing
  • Build your VM into a node binary for deployment
  • Understand what a Module is and how to create and upload one to Arweave as a VM template
  • Start (Spawn) a VM instance on the network using the Module ID

These steps enable you to transform your business logic into a standardized, cross-node executable, and verifiable service module in the HyMatrix network. Ultimately, your VM becomes a persistent, trustworthy computing unit in the global decentralized computing network.

Install hymx​

To get started, install the hymx toolkit in your local development environment:

go get github.com/hymatrix/hymx

Then import it in your Go project:

import "github.com/hymatrix/hymx/server"

Mount Your Virtual Machine​

Mounting is the process of registering your custom VM with a local hymx server during development. This allows the node to instantiate and call your VM logic.

Here is a minimal example:

s := server.New(bundler, redisURL, arweaveURL, hymxURL, nodeInfo)
// Mount your VM implementation
s.Mount("myorg.myvm.1.0.0", myvm.SpawnMyVM)
s.Run(port)

  • server.New(...): Creates the server instance.

  • Mount(...): Registers your VmSpawnFunc function, e.g. myvm.SpawnMyVM.

    The first argument is the ModuleFormat — a unique string to identify your VM in the network. It's used later to spawn VM instances.

    Naming convention: "organization.type.version", such as:

    • acme.imageprocessor.1.0.0
    • team.aibot.0.1.2
    • org.yourvm.1.0.0

  • Run(port): Starts the local server on the specified port.

You can mount multiple VMs in one server instance during development for easier testing and debugging.

Build the HyMatrix Node​

After mounting, the next step is to build your VM into the hymx node:

  • The build process compiles your VM and integrates it into a node binary.
  • Once running, your node will support the VM type and can handle messages targeting it.

This ensures your VM is standardized and runnable on any compatible HyMatrix node.

See full reference code 👉 main.go

The Meaning of Mount and Build​

  • Mount is for local testing — it registers your VM during development with a local hymx node.
  • Build is for deployment — it compiles your VM into the node program, allowing it to serve execution requests on the network.

Together, these steps allow developers to turn business logic into standard HyMatrix modules, ready for global decentralized execution and verifiable computation.

Creating a Module​

In HyMatrix, a Module is a template definition of a virtual machine stored on Arweave. It defines the VM type and parameters required to spawn instances.

To spawn a VM instance on the network, the associated Module must already be uploaded to Arweave. Nodes that have mounted your VM can then read this Module and instantiate the VM accordingly.

Here’s the Module structure:

type Module struct {
	Base
	ModuleFormat   string           `json:"Module-Format"`
	MemoryLimit    string           `json:"Memory-Limit"`
	ComputeLimit   string           `json:"Compute-Limit"`
	Tags           []goarSchema.Tag `json:"Tags,omitempty"`
}
  • ModuleFormat: The type and version of your VM (e.g. "myorg.myvm.1.0.0"). This must match your mounted VM identifier.
  • MemoryLimit, ComputeLimit: Optional resource limits.
  • Tags: Additional metadata.

After uploading a Module to Arweave, use the Module ID (i.e. the Arweave item.Id) to reference it in a spawn request:

type Process struct {
	Base
	Module      string           `json:"Module"`
	Scheduler   string           `json:"Scheduler"`
	FromProcess string           `json:"From-Process,omitempty"`
	Tags        []goarSchema.Tag `json:"Tags"`
}
  • Module: The Module ID on Arweave.
  • Scheduler: The target node (you can fill in your node’s AccId if you’ve joined the network).
  • FromProcess: For call chaining between VMs.
  • Tags: Additional parameters.

If a node has mounted your VM and has access to the specified Module, a Process message is all it takes to spawn a live VM instance.

Uploading a Module​

Before uploading a Module to Arweave, make sure your wallet has sufficient AR balance — uploading incurs storage fees. If balance is low, the upload will fail. Use an Arweave explorer or wallet to check your balance in advance.

Here’s a minimal Go example using hymx/utils and goar to upload a Module:

package main

import (
	"context"
	"fmt"

	"github.com/hymatrix/hymx/schema"
	"github.com/hymatrix/hymx/utils"
	"github.com/permadao/goar"
	goarSchema "github.com/permadao/goar/schema"
	goarUtils "github.com/permadao/goar/utils"
)

func main() {
	// 1. Load Arweave wallet
	signer, _ := goar.NewSignerFromPath("./testkey.json")
	bundler, _ := goar.NewBundler(signer)
	wallet := goar.NewWalletWithSigner(signer, "https://arweave.net")

	// 2. Create Module tags
	tags, _ := utils.ModuleToTags(schema.Module{
		Base:         schema.DefaultBaseModule,
		ModuleFormat: "myorg.myvm.1.0.0",
	})

	// 3. Create and sign an empty BundleItem
	item, err := bundler.CreateAndSignItem([]byte{}, "", "", tags)
	if err != nil {
		return
	}
	bundle, err := goarUtils.NewBundle(item)
	if err != nil {
		return
	}

	// 4. Upload to Arweave
	_, err = wallet.SendBundleTxSpeedUp(context.TODO(), 10, bundle.Binary, []goarSchema.Tag{}, 50)
	fmt.Println(item.Id, err)
}

The key field is ModuleFormat, which identifies the VM type.

After successful execution, the console will print item.Id — this is your Module ID, and you’ll use it in Process messages to spawn VMs across the HyMatrix network.