Run an Antspace Worker

Overview

This page details how to run the Bitmain Antspace container Worker. Select the development (mock) or real-container path.

Prerequisites

Review the common deployment prerequisites before you start

Deployment-specific requirements:

A Node.js service or script in your deployment that runs the MDK Worker and registers containers
A supported Antspace container reachable from the machine or container running the Worker over its REST HTTP API, typically port 8000

Development

Run against a mock

The Antspace Worker ships a mock container that answers its HTTP API with canned data. Run the mock in one terminal and the Worker in a second, both from the repository root.

Start a mock HK3 container:
```
npm run mock hk3 18001
```

Save this script as antspace-dev.js in the repository root. It is the boot call from Connect a container, pointed at 127.0.0.1:

'use strict'

const os = require('os')
const path = require('path')
const { getKernel } = require('@tetherto/mdk-core')
const { startAntspaceWorker } = require('@tetherto/mdk-worker-antspace')

const main = async () => {
  const kernel = await getKernel()

  const worker = await startAntspaceWorker({
    workerId: 'antspace-dev',
    model: 'hk3',
    storeDir: path.join(os.tmpdir(), 'mdk-dev', 'antspace'),
    allowedKeys: [kernel.getClientPublicKey()],
    seedDevices: [{
      info: { serialNum: 'HK3-DEV', container: 'dev' },
      opts: { address: '127.0.0.1', port: 18001 }
    }]
  })
  await kernel.registerWorker(worker.runtime.getPublicKey())

  console.log('Kernel HRPC key:', kernel.getPublicKey().toString('hex'))
  console.log('Device:', worker.services.provisioning.listDeviceIds()[0])
  console.log('Ctrl+C to stop.')
}

main().catch((err) => { console.error(err); process.exit(1) })

Run the script in a second terminal:
```
node antspace-dev.js
```

Expected output, with your own key and device ID:

Kernel HRPC key: de61f30cd7bd65923d9c8089e4fa684335a37371600e1610823a4fc20aba0247
Device: 183ded12-bf17-4b40-9970-5c535fd79916
Ctrl+C to stop.

The Kernel then pulls live telemetry (temperatures, cooling status, power) from the mock through the Worker. The mock's model and port options are in the Antspace README.

Connect a container

2.1 Pick your model

Use the Antspace README to confirm the model value for your container: hk3 or immersion. This guide uses hk3, replace it with the value for your container.

Add this code to the Node.js service or script that runs the MDK Worker in your deployment. The snippet shows the minimum boot call seeding one Antspace container, replace the example address and credentials with your container's values:

const { getKernel } = require('@tetherto/mdk-core')
const { startAntspaceWorker } = require('@tetherto/mdk-worker-antspace')

const kernel = await getKernel()

const worker = await startAntspaceWorker({
  workerId: 'antspace-rack-1',
  model: 'hk3',
  storeDir: './store/antspace-rack-1',
  allowedKeys: [kernel.getClientPublicKey()],
  seedDevices: [{
    info: { serialNum: 'HK3-A', container: 'container-A', location: 'site-a-01.container' },
    opts: { address: '192.168.1.100', port: 18001 }
  }]
})
await kernel.registerWorker(worker.runtime.getPublicKey())

allowedKeys lists the RPC callers the Worker accepts. The Worker refuses to start without it (ERR_WORKER_ALLOWED_KEYS_REQUIRED), so pass the Kernel's client key.

Make sure each container's address is reachable from the machine or container running the Worker before registering. Commands affect live cooling for racks of miners, prioritize thermal safety.

seedDevices only seeds a fresh, empty storeDir, once persisted, the device set survives restarts on its own. To add a container to an already-running fleet, send the registerThing command to the live Worker instead:

const { createMdkClient } = require('@tetherto/mdk-client')

const client = createMdkClient({ kernelKey: kernel.getPublicKey() })
await client.connect()
await client.sendWorkerCommand('antspace-rack-1', null, 'registerThing', {
  id: 'HK3-B',
  info: { serialNum: 'HK3-B', container: 'container-A' },
  opts: { address: '192.168.1.101', port: 18001 }
})

registerThing persists the container config immediately, but the running Worker does not pick it up until it is stopped and restarted (await worker.stop(), then call startAntspaceWorker again with the same storeDir and no seedDevices), there is no hot-add.

For the full seedDevices and registerThing option reference, the telemetry and command tables, and the shared install pattern, see the Antspace README and install pattern.

Troubleshooting

A working development run of antspace-dev.js prints the Kernel HRPC key and the registered device ID, then stays running until Ctrl+C.

If it does not print those values, or if npm run mock reports port 18001 already in use, the network and port checks in miner troubleshooting apply here too, the underlying HRPC and DHT requirements are the same across every Worker.

Next steps

Decide how to run the Worker service, Deployment topologies
Review telemetry units, command shapes, and error codes, the Antspace README