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

One command downloads the build for your machine, checks it against its published checksum, and puts it on your path. It asks for your password to write to /usr/local/bin.

curl -fsSL https://docs.katara.com/install.sh | sh

Nothing else is needed on a Mac: the node brings its own Python for the MLX runtime the first time it checks a bundle, and downloads the model weights itself. On Linux the node runs vLLM in a container, so Docker and the NVIDIA container toolkit must be installed.

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

curl -O https://docs.katara.com/bundles/llama-3.1-8b-instruct.v1.json
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; Models and bundles lists them.

Create the node’s key

katara-node id

Asks you for a passphrase, creates the service key in the node’s keystore, and prints its address. This key signs offers and receipts. It is not your wallet and cannot move funds. Every later command asks for the same passphrase; for an unattended service set it in KATARA_NODE_PASSPHRASE instead.

Register

In the portal at https://app.staging.katara.com, open Provider and register with:

• your payout address (defaults to your wallet),
• the service key address from katara-node id.

No address is needed: the node connects out to Katara. Operators who want the router to dial a public HTTPS address instead can register one; see Networking.

Registration is one transaction from your wallet, signed with your passkey; gas is covered, so the wallet needs no AVAX. 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.staging.katara.com \
  -in-per-mtok 100000 -out-per-mtok 300000

-wallet is the wallet address the portal shows, the same one you registered from. -gateway names the network: https://api.staging.katara.com is the public test network on Avalanche Fuji. 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.

The node holds one outbound connection to the gateway; jobs arrive on it and nothing listens on your machine. See Networking.

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 whose connection is down drops out of routing within a minute or two and returns when it reconnects. 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, -listen only if you registered a public address for direct dialing.

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.staging.katara.com -rpc https://api.avax-test.network/ext/bc/C/rpc

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.