Running a node

The node is one binary with five commands: detect hardware, check a bundle, create the signing key, print the registration, and serve. Run them in that order.

Install

Get the release for your platform from the releases page of the katara-node repository on GitHub and put it on your path. On macOS the bundle check installs the pinned MLX runtime into a private Python environment. On Linux the node runs vLLM in a container: install Docker and the NVIDIA container toolkit first.

Check your hardware

katara-node hw

Prints the chip and unified memory on a Mac, or each NVIDIA GPU with its memory and compute capability on Linux.

Check a bundle

katara-node adapter-check -manifest llama-3.1-8b-instruct.v1.json

Downloads the bundle’s pinned weights and runtime, verifies every hash, starts the model, and measures warm-up and time to first token against the bundle’s thresholds. A hash mismatch stops here: the node refuses to serve anything but the exact bundle.

Bundle manifests are published with each approved model; the catalog page lists where to get them.

Create the node’s key

katara-node id

Creates the service key in the node’s keystore on first run and prints its address. This key signs offers and receipts. It is not your wallet and cannot move funds.

Set KATARA_NODE_PASSPHRASE to protect the keystore; the node reads it from that variable.

Register

In the portal, open Provider and register with:

• your payout address (defaults to your wallet),
• the service key address from katara-node id,
• the public HTTPS address your node will answer on.

Registration is one transaction from your wallet, signed with your passkey. If you would rather send it yourself, katara-node register-calldata -payout … -service-uri … prints the transaction data; the wallet still signs it, never the node.

Serve

katara-node serve \
  -manifest llama-3.1-8b-instruct.v1.json \
  -wallet 0xYourWallet \
  -gateway https://api.katara.com \
  -service-uri https://node.example.com \
  -in-per-mtok 100000 -out-per-mtok 300000

The node checks the hardware again, prepares and starts the runtime, warms it up, and only then publishes its first offer. Prices are per million tokens in USDC base units: 100000 is 0.10 USDC per million input tokens. Change a price by restarting with new flags; the new offer replaces the old one.

It listens on 127.0.0.1:8470 for jobs. Put a reverse proxy or tunnel with a valid certificate in front of it and register that public address; see Networking. To terminate TLS in the node itself, pass -tls-cert and -tls-key.

The gateway tells the node which chain and settlement contract it serves and which router key signs jobs, so those never need configuring by hand. An offer the gateway accepts is the node’s heartbeat; a node that stops sending them drops out of routing within a minute or two. When the runtime stops answering, the node pauses offers, restarts the runtime, and resumes on its own.

Stop it with Ctrl-C. Jobs already in flight finish before the runtime shuts down.

Useful flags: -max-concurrency for how many jobs run at once (1 on a Mac, more on a large GPU), -profile to pick a profile inside a bundle with several, -workdir for where weights and environments live.

Status and earnings

While the node runs, http://127.0.0.1:8471/ shows what it is doing: runtime health, offers accepted, jobs served, tokens, receipts and acknowledgements. It is only reachable from the machine itself.

katara-node status -wallet 0xYourWallet -gateway https://api.katara.com -rpc https://sepolia.base.org

Reads your registration from the chain, sums every settlement paid to you, shows the payout address and, with -token, its USDC balance, and appends the running node’s counters when it is up. -json prints the same as JSON. Earnings come from the settlement contract’s own events, so they are right even if the node was down while they were paid.

What happens next

Each completed job returns a signed receipt. The router verifies it, settlement pays your address, less the 2% fee, and your earnings appear in the portal. See Providing inference for the flow.