Run a Hylon Node
Install the Hylon node binary, onboard it with a one-time setup code, and earn points for verified work. Beta program, points only, no token payouts.
Run a Hylon Node
Put a spare computer to work for the Hylon network. Download one binary, paste one setup code, and your machine starts leasing verification and benchmark tasks that the server independently re-verifies before awarding points.
Beta program: points, not tokens
The node program is in beta and rewards points, recorded in the Hylon node-program ledger. Points are not ORB, have no monetary value today, and there is no conversion from points to tokens. If a conversion path ever opens it will be a separate, explicitly announced step, and it is disabled by default. No page of these docs promises token amounts, and neither does the API: every node-program response carries "program_status": "beta" and a note stating that no token payouts are made or promised.
Current tasks are deterministic verification and benchmark jobs (digest chains the server recomputes itself). AI inference serving from community nodes is not live yet.
Requirements
- A 64-bit machine running macOS, Linux, or Windows that can stay online.
- Outbound HTTPS access to
https://api.orbai.world(no inbound ports, NAT and CGNAT are fine). - An OrbVPN / Hylon account (any account works, no subscription required).
Step 1: Download the binary
All builds are published to a public, checksummed download location. Pick the one matching your platform:
Verify your download against the published checksums, then make it executable:
# macOS (Apple Silicon) example
curl -LO https://orb.blob.core.windows.net/hylon-node/hylon-node-darwin-arm64
curl -LO https://orb.blob.core.windows.net/hylon-node/SHA256SUMS
shasum -a 256 --check --ignore-missing SHA256SUMS
chmod +x hylon-node-darwin-arm64On Linux use sha256sum --check --ignore-missing SHA256SUMS instead of shasum.
macOS Gatekeeper
If you downloaded the binary with a browser rather than curl, macOS may quarantine it. Clear the flag with xattr -d com.apple.quarantine hylon-node-darwin-arm64 before running it.
Step 2: Get a one-time setup code
The setup code ties the node to your account. It is single use and expires after 15 minutes.
From the dashboard (recommended)
Sign in at app.hylon.ai/nodes and click Add node. The dashboard shows the code, its expiry, and the exact command to paste.
Or from the API
Send POST /api/v1/hylon/nodes/setup-code with your session bearer token. Setup codes must be minted from a signed-in session; requests authenticated with a Hylon API key are refused.
curl -X POST https://api.orbai.world/api/v1/hylon/nodes/setup-code \
-H "Authorization: Bearer <YOUR_SESSION_JWT>"{
"success": true,
"data": {
"code": "M3KTPX7Q",
"expires_at": "2026-07-28T12:34:56Z",
"command": "orbmesh node --setup-code M3KTPX7Q",
"program_status": "beta",
"note": "Beta: nodes run verification and benchmark tasks. Rewards are points in the node-program ledger; no token payouts are made or promised."
}
}Step 3: Run the node
./hylon-node-darwin-arm64 --setup-code M3KTPX7QThe command field returned with your setup code shows the generic form orbmesh node --setup-code <CODE>. The downloaded binary accepts both invocations: run it directly with --setup-code, or with a leading node argument; they behave identically.
On first run the node:
- Redeems the setup code at
POST /api/v1/hylon/node-agent/registerand receives its credentials (node_uuidandnode_key). The key is returned exactly once; the server stores only a hash of it. - Saves its identity to
~/.orbmesh/node.json(file mode 0600). Later runs load this file, so the setup code is never needed again. - Detects its capabilities (CPU cores, RAM, GPU, device type) and reports them honestly. The server derives the node tier from them.
- Starts the work loop: it leases tasks every 15 seconds, executes them, and reports completions.
Useful flags
| Flag | Default | Purpose |
|---|---|---|
--setup-code | (none) | One-time onboarding code from the dashboard. Only needed on first run. |
--orbnet-api | https://api.orbai.world | OrbNet REST base URL for the node-agent task plane. |
--state-dir | ~/.orbmesh | Where the node identity (node.json) is stored. |
--name | your hostname | Display name shown in the dashboard. Used at onboarding. |
--max-tasks | 4 | Maximum tasks leased per cycle. |
--lease-interval | 15s | How often the node asks for work. |
How work and points flow
Lease
The node calls POST /api/v1/hylon/node-agent/tasks/lease with its X-Node-UUID and X-Node-Key headers. Each leased task is exclusive to the node for 5 minutes, after which unfinished tasks become reclaimable.
Execute
v1 tasks are sha256 digest chains: verify.recompute uses light chains, bench.cpu uses heavier ones. Both are deterministic on purpose.
Report
The node posts the resulting digest to POST /api/v1/hylon/node-agent/tasks/{id}/complete.
Server re-verification
The server recomputes the digest chain itself. Only completions the server verifies earn points, so faked work is never rewarded. Each task can be awarded at most once.
Point rates
| Task kind | Points per verified task |
|---|---|
verify.recompute | 1 |
bench.cpu | 5 |
These are the current defaults. Rates are operator-tunable and may change; your points ledger always reflects the rate at the time each task was verified.
Node tiers
The server derives a coarse tier from reported capabilities:
| Tier | Rule |
|---|---|
mobile | Device type is a phone or tablet, regardless of core count. |
server | Has a GPU, or 8 or more CPU cores. |
desktop | Everything else. |
Monitoring your nodes
See your enrolled nodes, their status, points, and truthful contribution counters at app.hylon.ai/nodes, or via the API:
curl https://api.orbai.world/api/v1/hylon/nodes \
-H "Authorization: Bearer <YOUR_SESSION_JWT>"Each node reports status (online, offline, or disabled), tier, points, last_seen, and a contributions block. A node counts as online when it has checked in within the last 5 minutes; the lease loop doubles as the heartbeat. The compute_units and inference_requests counters stay at zero until real compute and inference serving ship; the program never fabricates contribution numbers.
Troubleshooting
Setup code invalid
Codes are single use and expire after 15 minutes. Mint a fresh one from the dashboard and run the command again.
Invalid node credentials (401)
The node.json identity no longer matches the server (for example the node was disabled). Delete ~/.orbmesh/node.json and onboard again with a new setup code.
No tasks leased
The queue self-replenishes with verification tasks when a node asks for work, so persistent empty leases usually mean a connectivity issue. Check that the machine can reach https://api.orbai.world.
Stopping or removing a node
Stop the process any time; leased tasks it held simply become reclaimable after 5 minutes. To retire a machine, stop the process and delete the state directory. The node then shows as offline in your list.