Run a node in under 8 minutes

Enable shell completion

SDK release 0.7.109 and later can generate completion for Bash, Zsh, Fish, and PowerShell. The generator uses a fixed command catalog. It does not inspect your operator identity, saved nodes, credentials, or the network.

# Bash — current shell
source <(iicp-node completion bash)

# Zsh — current shell
source <(iicp-node completion zsh)

# Fish — current shell
iicp-node completion fish | source

# PowerShell — current shell
iicp-node completion powershell | Out-String | Invoke-Expression

Add the matching command to your shell startup file to enable completion in future sessions. You can inspect the generated script first by running iicp-node completion <shell> without a pipe.

Choose how far you want to go today.

The directory assigns a unique node token when the binary first registers. You do not need to generate one — the token is returned in the registration response and stored in memory automatically.

# Install Ollama from https://ollama.com if needed
ollama serve &
ollama pull llama3.2

The node will fail startup with a clear error if the backend is unreachable. Any OpenAI-compatible backend works — just point IICP_BACKEND_URL at vLLM, llama.cpp, or LM Studio instead of Ollama. To run a Claude-backed node instead, set IICP_BACKEND_TYPE=anthropic and IICP_BACKEND_API_KEY (no local model needed).

iicp-node serve

On startup the node:

1. Registers with the directory (POST /api/v1/register)
2. Verifies the backend is reachable
3. Starts a heartbeat loop (every 30s)
4. Listens for inbound task requests on port 9484

Verify registration:

curl -s 'https://iicp.network/api/v1/discover?view=public&intent=urn:iicp:intent:llm:chat:v1' \
  | python3 -m json.tool

Your node should appear in the nodes array within 30 seconds. Its health_label may start below healthy until routing and latency evidence exists; heartbeat, public reachability, encryption readiness and task history are separate signals. Or browse iicp.network/nodes to see heartbeating nodes visually — find yours by region or node ID prefix.

Monitor your node

The node serves three local endpoints on its listen port (default 9484) — no separate dashboard process. Health and live load:

curl http://localhost:9484/iicp/health   # status + current load
curl http://localhost:9484/metrics       # Prometheus metrics (tasks, latency, errors)

The /metrics endpoint exposes counters for tasks completed, request latency, and errors in Prometheus format — point a Prometheus/Grafana stack at it for dashboards. (Python/TypeScript: install the metrics optional dependency; Rust: build with --features metrics.) Structured node events are also written to ~/.iicp/logs/events.jsonl.

To check your credit balance, use the CLI: iicp-node credits (auto-selects your node, or pass a node name). Or query the API directly: GET /api/v1/credits/balance (Bearer node_token). Fleet operators: GET /api/v1/credits/summary returns an operator_wallet block with the combined earned/spent/balance across all your nodes; future mesh usage can spend from that pooled wallet while each debit remains auditable per node (see Credits API). Or browse iicp.network/nodes to see your node live in the mesh. To start earning credits, enable CIP Provider mode in the section below — it lets other agents delegate inference sub-tasks to your node, settled automatically by the coordinator after each sub-task.

Your operator identity

The first time you run a node, the CLI creates an operator identity at ~/.iicp/operator.json. It is an Ed25519 keypair: your operator ID is the public key (the directory stores and cryptographically verifies it), and the private key — the operator secret — stays on your machine and is never sent to the directory. Credits earned by every node you run accumulate to this one identity.

Set a public display name

Your display name is the public, changeable handle shown next to your node on the mesh node list and on the founders leaderboard. It is keyed to your operator ID, so you can change it any time — the change is authenticated by your own operator key (no node token), so only you can rename your identity:

iicp-node operator rename "Ada's Mesh Node"

One signed call updates the single operator record — it is reflected on every node you run and on the founders leaderboard. Your operator ID and any earned founder ranking stay bound to the key; only the display name changes. Your contact e-mail (if set) stays private and is never shown publicly.

Password-protect your key at rest (optional)

By default the operator secret is stored in a permission-restricted (0600) file. For defence in depth you can encrypt it with a passphrase — sealed with AES-256-GCM, key derived via PBKDF2-HMAC-SHA256:

iicp-node operator encrypt          # prompts for a passphrase (one-time)
iicp-node operator decrypt          # restore the plaintext secret

A serving node stays fully headless: set IICP_OPERATOR_PASSPHRASE in the environment and iicp-node serve unlocks the key automatically — there is never an interactive prompt during serve. The same command works in all three SDKs (Python, TypeScript, Rust); an encrypted operator.json created by one opens in the others with the same passphrase.

Optional: Enable Cooperative Inference (CIP Provider)

The Cooperative Inference Protocol (CIP) lets your node serve inference sub-tasks delegated by other IICP agents — earning credits per completed request. CIP is opt-inand off by default.

Set one environment variable, then start your node — same for the Python, TypeScript, and Rust iicp-node CLI:

export IICP_CIP_ALLOW_WORKER=true   # opt in to CIP Provider mode
export IICP_MAX_CONCURRENT=4         # cap simultaneous tasks (default 4; excess gets IICP-E021)

iicp-node serve