# Running a node > Install, check your hardware against a bundle, create the node's key, and register. Section: Providing inference. Web page: https://docs.katara.com/providers/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. ```sh 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: ```sh 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](https://docs.katara.com/providers/windows-native.txt) with four available Blackwell models. Follow [Linux and Windows setup](https://docs.katara.com/providers/linux-windows.txt) for prerequisites and the Windows installer. ## Check your hardware ```sh 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 ```sh 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](https://docs.katara.com/concepts/models.txt) lists them. ## Create the node's key ```sh 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](https://docs.katara.com/about/networks.txt) 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](https://docs.katara.com/providers/networking.txt). 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: ```sh katara-node serve ``` Spell the flags out to override any of it, or to run a node the installer did not set up: ```sh 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](https://docs.katara.com/providers/networking.txt). 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 ```sh 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. ```sh 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 ` 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](https://docs.katara.com/providers/windows-native.txt#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. ```sh 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](https://docs.katara.com/providers/overview.txt) for the flow.