Beam Orchestrator Guide

An orchestrator manages a worker pool on Beam. BeamCore sends work over NATS; the orchestrator selects workers and relays offers and results over BeamLink/WCP. The worker moves the data.

1. Prepare the host

You need Go 1.24+, a Bittensor miner hotkey registered on subnet 105, and access to BeamCore, the NATS control gateway, and Bittensor. Workers also need a reachable TLS 1.3 WCP endpoint on your orchestrator. Obtain a TLS certificate and key for that endpoint; give workers the CA certificate and server name they should trust.

Run subnet registration from your wallet host so the coldkey stays off the orchestrator server. Check the transaction and fee before submitting it:

btcli subnet register --netuid 105 --subtensor.network finney \
  --wallet.name YOUR_WALLET --wallet.hotkey YOUR_HOTKEY

Our server prerequisites guide covers the basic host setup.

2. Build the orchestrator

git clone https://github.com/Beam-Network/beam.git
cd beam
mkdir -p bin
go build -trimpath -o bin/beam-orchestrator ./cmd/beam-orchestrator
./bin/beam-orchestrator version

Keep the clone and its data/orchestrator/ directory on persistent storage. That directory holds the local identity, task state, and journals.

3. Register with BeamCore

Subnet registration and BeamCore registration are separate steps. Sign the exact message YOUR_HOTKEY_SS58:10 with that hotkey, where 10 is the fee percentage in the request below. Replace every placeholder before sending:

curl -X POST https://beamcore.b1m.ai/orchestrators/register \
  -H 'Content-Type: application/json' \
  -d '{
    "hotkey": "YOUR_HOTKEY_SS58",
    "signature": "0xYOUR_SIGNATURE",
    "fee_percentage": 10,
    "name": "my-orchestrator",
    "region": "global",
    "url": "https://orchestrator.example.com",
    "max_workers": 1000
  }'

Save the returned orchestrator_id and api_key securely. BeamCore returns the API key only at first registration. Register before starting the NATS connection, or BeamCore can reject it as orchestrator_not_routable. See the official registration details if you need to change metadata later.

4. Configure and run

Create an environment file outside the Git clone, readable only by the service administrator. For example, place it at /etc/beam/orchestrator.env with mode 600:

BEAM_ENV=prod
BEAM_ORCHESTRATOR_ID=YOUR_ORCHESTRATOR_ID
BEAM_BITTENSOR_HOTKEY=YOUR_HOTKEY_SS58
BEAMCORE_NATS_URL=tls://orch-gateway.b1m.ai:4222
BEAMCORE_NATS_USER=YOUR_HOTKEY_SS58
BEAMCORE_NATS_PASSWORD=YOUR_ORCHESTRATOR_API_KEY
BEAM_PUBLIC_API_URL=https://beamcore.b1m.ai
BEAMCORE_GATEWAY_URL=https://orchestrator.example.com
BEAM_WCP_LISTEN_ADDR=0.0.0.0:8782
BEAM_WCP_TLS_CERT=/path/to/wcp.crt
BEAM_WCP_TLS_KEY=/path/to/wcp.key

BEAMCORE_GATEWAY_URL is your public orchestrator URL. BEAM_WCP_LISTEN_ADDR is the TLS listener workers connect to. Allow the WCP port through your firewall; keep the owner-local HTTP API on 127.0.0.1:8781.

For a persistent process, use systemd. Replace the user and absolute clone path, then save this as /etc/systemd/system/beam-orchestrator.service:

[Unit]
Description=Beam Orchestrator
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_LINUX_USER
WorkingDirectory=/ABSOLUTE/PATH/beam
EnvironmentFile=/etc/beam/orchestrator.env
ExecStart=/ABSOLUTE/PATH/beam/bin/beam-orchestrator serve --netuid 105
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Keep the environment file readable by systemd; the service user needs read access to the TLS files and write access to the clone’s data/ directory. Start it after replacing all placeholders:

sudo systemctl daemon-reload
sudo systemctl enable --now beam-orchestrator
sudo journalctl -fu beam-orchestrator

5. Add workers and check health

After a worker has registered with BeamCore, get its worker_id and persistent node ID from the worker operator. Register its membership on the orchestrator host using the local API:

curl -X POST http://127.0.0.1:8781/v1/orchestrator/memberships \
  -H 'Content-Type: application/json' \
  -d '{"OrchestratorID":"YOUR_ORCHESTRATOR_ID","WorkerID":"YOUR_WORKER_ID","NodeID":"YOUR_WORKER_NODE_ID","Status":"active"}'

Check the local process and its logs:

curl http://127.0.0.1:8781/healthz
curl http://127.0.0.1:8781/v1/orchestrator/manifest
sudo journalctl -u beam-orchestrator -n 100 --no-pager

A healthy local endpoint confirms the process is running; the manifest shows its local view of connected worker capabilities. Check the Beam dashboard for NATS connection, readiness, connected workers, and task history before assuming it can receive production work.

New orchestrators start in the qualifying pool and receive calibration work. Production assignments require qualification; PRISM scoring controls routing within the relevant pool.

6. Updating

Build a new binary from the official source, then restart the service. Record the revision and binary provenance first:

git rev-parse HEAD
go version -m bin/beam-orchestrator
git pull --ff-only
go build -trimpath -o bin/beam-orchestrator ./cmd/beam-orchestrator
sudo systemctl restart beam-orchestrator

Troubleshooting

• orchestrator_not_routable on NATS registration: complete BeamCore registration first. Check that its hotkey is registered on the same chain and netuid as the process.
• duplicate_control_session: another orchestrator is using the same hotkey. Stop the duplicate before restarting this service.
• invalid client protocol: record the binary’s go version -m output, then rebuild from the official source. The production NATS endpoint uses tls://orch-gateway.b1m.ai:4222.
• Worker cannot join: compare BEAM_WCP_LISTEN_ADDR with the worker’s BEAM_WCP_ADDRESS, then check the firewall, TLS certificate, worker CA, server name, and membership IDs.
• Healthy but no transfer work: check NATS readiness and connected worker capabilities. A new orchestrator receives calibration work in the qualifying pool before it can receive production assignments.