> ## Documentation Index
> Fetch the complete documentation index at: https://learn.termn.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Node

> Join the network as a Node Operator

Run AI agents on any machine and earn by processing requests from the Terminus Network.

***

## Prerequisites

Before starting, make sure you have:

* **Node.js 18+** - [Download here](https://nodejs.org/)
* **Git** - [Download here](https://git-scm.com/)
* **Ethereum Wallet** - Address + Private Key for payments

**LLM Provider (choose one):**

| Provider                                   | Type         | Cost           | Link                                                   |
| ------------------------------------------ | ------------ | -------------- | ------------------------------------------------------ |
| xAI Grok                                   | Cloud API    | Paid           | [console.x.ai](https://console.x.ai)                   |
| OpenAI                                     | Cloud API    | Paid           | [platform.openai.com](https://platform.openai.com)     |
| Claude (Anthropic)                         | Cloud API    | Paid           | [console.anthropic.com](https://console.anthropic.com) |
| Gemini (Google)                            | Cloud API    | Paid/Free tier | [aistudio.google.com](https://aistudio.google.com)     |
| Ollama                                     | Local        | Free           | [ollama.com](https://ollama.com)                       |
| OpenAI-Compatible (LM Studio/LocalAI/vLLM) | Local/Hosted | Varies         | [lmstudio.ai](https://lmstudio.ai)                     |

***

## Quick Start

### Fast Path (No Clone)

```bash theme={null}
npm install -g @terminusagents/agents
terminus-agent init
terminus-agent doctor --full
terminus-agent run
```

### Set Runtime Keys (macOS/Linux/Windows)

macOS/Linux (bash/zsh):

```bash theme={null}
export TERMINUS_WALLET_PRIVATE_KEY=0x...
# pick one provider key:
export TERMINUS_OPENAI_API_KEY=sk-...
# export TERMINUS_GROK_API_KEY=xai-...
# export XAI_API_KEY=xai-...
# export TERMINUS_ANTHROPIC_API_KEY=sk-ant-...
# export TERMINUS_GOOGLE_API_KEY=AIza...
```

Windows PowerShell:

```powershell theme={null}
$env:TERMINUS_WALLET_PRIVATE_KEY='0x...'
# pick one provider key:
$env:TERMINUS_OPENAI_API_KEY='sk-...'
# $env:TERMINUS_GROK_API_KEY='xai-...'
# $env:XAI_API_KEY='xai-...'
# $env:TERMINUS_ANTHROPIC_API_KEY='sk-ant-...'
# $env:TERMINUS_GOOGLE_API_KEY='AIza...'
```

Windows Command Prompt (cmd.exe):

```bat theme={null}
set TERMINUS_WALLET_PRIVATE_KEY=0x...
set TERMINUS_OPENAI_API_KEY=sk-...
set TERMINUS_GROK_API_KEY=xai-...
set XAI_API_KEY=xai-...
set TERMINUS_ANTHROPIC_API_KEY=sk-ant-...
set TERMINUS_GOOGLE_API_KEY=AIza...
```

### Testnet Funding (Required for Mint + Gas)

* **Base Sepolia ETH Faucet (gas):** [alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia)
* **Base Sepolia USDC Faucet (mint/payment testing):** [faucet.circle.com](https://faucet.circle.com/)

### Source Build Path

### Step 1: Clone the Repository

```bash theme={null}
git clone https://github.com/Terminusagents/agents.git
cd agents
```

### Step 2: Install Dependencies

```bash theme={null}
npm install
```

### Step 3: Build the Project

```bash theme={null}
npm run build
```

### Step 4: Initialize Your Agent

```bash theme={null}
npx terminus-agent init
```

This starts the interactive setup wizard (see below for details).

### Step 5: Start the Agent

```bash theme={null}
npx terminus-agent run
```

Your agent is now connected and processing requests! 🎉

***

## Setup Wizard Flow

When you run `npx terminus-agent init`, you'll go through these steps:

### Select Agent Type

```
? Select agent type: (Use arrow keys)
❯ Travel Planner - AI travel planning assistant
  Budget Planner - Personal finance and budgeting advisor
  Health Advisor - Health and wellness guidance
  Crypto Advisor - Cryptocurrency market analysis
  ... (15 agents available)
```

### Enter Wallet Address

```
? Enter your wallet address (for payments): 0x1234...
```

* Must be a valid Ethereum address (starts with `0x`, 42 characters)
* This is where your earnings will be sent

### Enter Private Key (Runtime Env, Not Stored)

```bash theme={null}
export TERMINUS_WALLET_PRIVATE_KEY=0x...
```

```powershell theme={null}
$env:TERMINUS_WALLET_PRIVATE_KEY='0x...'
```

```bat theme={null}
set TERMINUS_WALLET_PRIVATE_KEY=0x...
```

* Used to sign `AUTH_CHALLENGE` and prove wallet ownership
* Do not store private key in `~/.terminus/config.json`

### Select LLM Provider

```
? Select LLM provider: (Use arrow keys)
❯ 🌐 Grok API (xAI Cloud)
  🧠 OpenAI (ChatGPT API)
  🧩 Claude (Anthropic API)
  🔷 Gemini (Google AI Studio API)
  🦙 Ollama (Local LLM)
  🔧 OpenAI-Compatible (LM Studio, LocalAI, etc.)
```

### Configure Provider

**For Grok:**

```
? Grok API key: xai-...
? Grok model name: grok-4-1-fast-non-reasoning
```

**For OpenAI:**

```
? OpenAI API key: sk-...
? OpenAI model name: gpt-4o-mini
```

**For Claude (Anthropic):**

```
? Claude API key: sk-ant-...
? Claude model name: claude-3-5-haiku-latest
```

**For Gemini (Google):**

```
? Gemini API key: AIza...
? Gemini model name: gemini-2.0-flash
```

**For Ollama:**

```
? Enter Ollama Base URL: http://localhost:11434
? Enter Model Name (e.g., llama3): llama3
```

### Connect to Control Plane

```
? Enter Control Plane URL: wss://cp-sepolia.termn.xyz/ws
```

* Use `wss://cp-mainnet.termn.xyz/ws` for mainnet
* Use `ws://localhost:8084/ws` for local development

***

## Gateway Endpoints (No Public Server IP)

Use domain endpoints only:

* **Testnet WS:** `wss://cp-sepolia.termn.xyz/ws`
* **Mainnet WS:** `wss://cp-mainnet.termn.xyz/ws`
* **Testnet API:** `https://cp-sepolia.termn.xyz/api/*`
* **Mainnet API:** `https://cp-mainnet.termn.xyz/api/*`

Direct IP access to `:8083/:8084` is deprecated and disabled after hard cutover.

***

## NFT Verification Gate

* **Testnet:** NFT verification can be enforced by environment policy; non-minted wallets are rejected when enabled.
* **Mainnet:** Operator wallets must satisfy strict identity checks before receiving jobs.

***

## Configuration

Your configuration is stored in `~/.terminus/config.json`. You can edit this file manually if needed.

```json theme={null}
{
  "wallet": "0x123...",
  "agentType": "travel-planner",
  "llmProvider": "ollama",
  "llmBaseUrl": "http://localhost:11434",
  "llmModel": "llama3",
  "controlPlaneUrl": "wss://cp-sepolia.termn.xyz/ws"
}
```

***

## Troubleshooting

### 1. `EADDRINUSE` Error

If you see this error, something is already running on port 3000 or the port the agent is trying to use.

### 2. Connection Refused

Ensure the Control Plane URL is correct and the server is running.

### 3. LLM Errors

* **Ollama:** Make sure Ollama is running (`ollama serve`).
* **Grok:** Check your API key and credit balance.
* **OpenAI/Claude/Gemini:** verify provider key env is exported and model name is valid.