Running a node

The node is one binary with commands to 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.

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

On a terminal the installer then walks you through the rest: it lists the approved models this machine can serve, fetches the bundle you pick, runs the bundle check with the download shown as it happens, asks for your wallet, how many jobs to serve at once and your prices (with defaults), keeps the answers in ~/.katara-node/setup.env, and starts the node when you say so. The node asks for its keystore passphrase itself. The sections below are the same steps by hand.

Where it lands

If a katara-node is already on your path, the installer replaces that one, asking for a password if the directory needs it. That is deliberate: installing a second copy somewhere else would leave your shell running whichever comes first, and an upgrade that appears to do nothing is worse than being asked to authenticate.

On a first install it picks the first directory it can write to: /usr/local/bin, then Homebrew’s /opt/homebrew/bin, then ~/.local/bin, which it creates. Most machines are asked for nothing. Set KATARA_INSTALL_DIR to choose somewhere else; if that directory is not on your shell’s path, the installer prints the line to add.

A directory you do not own asks for an administrator password. On a Mac you can answer that with Touch ID instead of typing, once, for every command that asks:

sudo cp /etc/pam.d/sudo_local.template /etc/pam.d/sudo_local
sudo sed -i '' 's/^#auth/auth/' /etc/pam.d/sudo_local

The setting survives system updates. It applies to sudo in any terminal, not just this installer.

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. The installer can prepare Docker and the NVIDIA container toolkit on Ubuntu. Windows supports a WSL path and a native Windows app with four available Blackwell models. Follow Linux and Windows setup for prerequisites and the Windows installer.

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 and native Windows.

Check a bundle

katara-node bundles
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

bundles lists the approved models this machine can serve, with what each needs and the compatible profile index; bundles -all adds the ones it cannot and why.

adapter-check is an optional diagnostic and certification command. It downloads pinned artifacts, verifies their hashes and exercises the runtime and performance floors. It is not required by the installer. Normal serving verifies artifacts and checks runtime output, with performance observations recorded by default. Use serve -enforce-performance only when you want the optional performance floors enforced. A hash mismatch still prevents serving.

Bundle manifests are published with each approved model; Models and bundles lists them.

Create the node’s key

katara-node id

On first run it asks for a passphrase, creates the service key in the node’s keystore, and prints its address. After that it prints the address without asking, since the keystore carries it in the clear. This key signs offers and receipts. It is not your wallet and cannot move funds. Starting the node asks for the same passphrase; for an unattended service set it in KATARA_NODE_PASSPHRASE instead.

Register

A node registers on the network it serves. In the portal at https://platform.katara.com, choose Live or Test to match, 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

If the installer set this machine up, its model, runtime profile, key location, wallet and prices are in ~/.katara-node/setup.env and serving needs nothing else:

katara-node serve

Spell the flags out to override any of it, or to run a node the installer did not set up:

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

A flag wins over the environment, which wins over the saved file.

-wallet is the wallet address the portal shows, the same one you registered from. -gateway names the network: https://api.katara.com serves Live, paid in USDC on Avalanche C-Chain, and https://api.katara.com/test serves Test, paid in test USDC on Avalanche Fuji. The installer asks for it and offers Live; answer https://api.katara.com/test for a Test node. 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.

A node serves one network. To serve both from one machine, run a second node with its own -keystore, -workdir and -status-listen, and register its service key on the other network.

Which build is running

katara-node version

The node also prints it as the first line of every run. Worth checking if an upgrade seems to have changed nothing: two copies on one machine, with the shell picking the older, looks identical to an upgrade that failed.

Keeping it up to date

On macOS and Windows, a running node checks when serving starts and every half hour afterward. It prints the installed and published versions, using color only in supported terminals. It says what it found either way, so a check that could not run does not look like good news. It keeps serving regardless: being out of date does not stop anything. -version-check-every changes the interval and -no-version-check turns it off.

katara-node upgrade

On macOS and Linux, this downloads the published build for your machine, checks it against the published checksum, and replaces the binary in place. Checking and upgrading use the saved release channel; -base overrides it for an upgrade. A running node carries on with the copy it started from, so nothing in flight is interrupted; restart it when it suits you. If the binary sits somewhere you do not own, the command says to run it with sudo.

katara-node upgrade -version <version> installs a named one instead of the newest, which is how you go back.

On native Windows, stop serving and choose 4. Check for an update in Katara Node. The app shows the available version and asks before installing. Matching versions report No update available. Network failures leave the installed build in place.

Native Windows setup also saves your GPU allocation and concurrency. Select one NVIDIA card or several cards sharing the active model, then choose 1–8 simultaneous requests. Each start checks the selected configuration before accepting work. See Concurrency and GPU allocation.

Serving activity

The console prints a start and outcome for each inference request handled by the node. Completed and partial requests show input/output tokens, duration, first-token timing when measured, and the signed receipt amount in USDC. Failures and cancellations show a reason without including inference content. Availability messages describe the asking price and concurrency limit; they do not indicate a request or payment.

A gateway acknowledgement shows the acknowledged amount, fee and expected payment. Payment confirmed appears only after a matching settlement is found in a finalized block on the configured chain. It includes the actual amount, fee, net earnings and transaction reference. A receipt or acknowledgement alone leaves payment pending.

Payment checks run every 15 seconds and need no RPC of your own. On the Live network the node asks Katara’s public settlement index (https://index.katara.com/graphql) which transactions paid your address, then checks each transaction’s receipt on the chain’s public RPC: the settlement contract’s event, your address, the job, the amounts, success and a finalized block. Nothing the index reports counts until the receipt shows it. If the index is unreachable or behind the chain, the node searches the chain’s settlement events itself, more slowly. A Test node always searches the chain itself, since the Test network has no public index. If the public RPC limits the node’s requests, checks pause and resume on their own.

Your own RPC is optional. Set -payment-rpc or KATARA_RPC_URL and the node searches the chain through it and does not use the index; its chain must match the gateway. -payment-index off makes a node without its own RPC search the public RPC instead of using the index. If confirmation is unavailable, requests keep serving and payment status reports the problem. Pending receipt references, amounts and scan positions are kept under the runtime folder’s activity directory so checks resume after restart. No prompts, responses, tool arguments, buyer identities or credentials are saved there.

Every minute, the console summarizes connectivity, request totals, pending receipt amounts and confirmed net earnings tracked by this node. -summary-every changes that interval; -summary-every 0 disables summaries. Request counters start over with the process; payment totals survive restart when the history file is writable.

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, acknowledgements, pending payments and confirmed earnings tracked by this node. The page refreshes every five seconds and stays accessible while the console serves. It is only reachable from the machine itself.

katara-node status -wallet 0xYourWallet -gateway https://api.katara.com -rpc https://api.avax.network/ext/bc/C/rpc

For a Test node, use -gateway https://api.katara.com/test -rpc https://api.avax-test.network/ext/bc/C/rpc. The command 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 Katara’s fee (2%, plus a fixed 0.012 USDC (0.018 with upto) on a reply paid per request with x402), and your earnings appear in the portal. See Providing inference for the flow.