/docs/cip-worker-setup

CIP worker setup

A CIP worker is a node that accepts inference sub-tasks dispatched by a coordinator on the IICP mesh. Workers earn credits for each completed sub-task. Enabling worker mode is a two-line config change — the node handles receipt signing and credit settlement automatically.

Worker mode is opt-in via one environment variable — then start (or restart) your node. The same variables work for the Python, TypeScript, and Rust iicp-node CLIs.

export IICP_CIP_ALLOW_WORKER=true   # accept CIP sub-tasks from coordinators
export IICP_MAX_CONCURRENT=4         # overall concurrent task cap (default 4)

iicp-node serve

After (re)starting with the variable set, the node re-registers with the directory, which sets allow_remote_inference: true on the node record as part of the registration payload, making your node discoverable by coordinators.

Query the discover endpoint and confirm your node appears with cip_capable: true:

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

{
  "count": 7,
  "nodes": [
    {
      "node_id": "urn:iicp:node:...",
      "cip_capable": true,
      "allow_remote_inference": true,
      "reputation_tier": "silver",
      ...
    }
  ]
}

Your node should appear in the list within one heartbeat cycle (≈ 30 seconds). If it does not appear, verify IICP_CIP_ALLOW_WORKER=true is exported and the node has restarted since the change.

Coordinator nodes send CIP sub-tasks to your POST /v1/task endpoint — the same endpoint used for standard inference tasks. The CALL body includes a cip envelope that identifies the task as a sub-task.

Example CIP CALL (abridged)

POST /v1/task
Authorization: Bearer <your-node-token>

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "intent": "urn:iicp:intent:llm:chat:v1",
  "payload": { "messages": [...] },
  "trace": {
    "cip_role": "coordinator",
    "cip_session_key": "sess_abc123"
  },
  "cip": {
    "cip_parent_task_id": "550e8400-...",
    "cip_role": "worker"
  }
}

Your node validates the CIP fields, runs inference locally, and returns a RESPONSE that includes a signed receipt. You do not need to implement any of this manually — the node runtime handles validation (CIP-V03/V04/V05), signing (CIP-TC9C), and the response wire format (CIP-W01).

When your node completes a CIP sub-task, it automatically:

1. Signs a cip_receipt with HMAC-SHA256 using your node HMAC key— provisioned by the directory at registration and stored in your node's local state.
2. Includes the receipt in the RESPONSE body alongside the inference result.
3. The coordinator verifies the receipt and submits it to POST /api/v1/credits/award on your behalf.
4. Credits are added to your node's ledger balance.

Example CIP RESPONSE (abridged)

{
  "task_id": "550e8400-...",
  "status": "success",
  "result": { "choices": [...] },
  "trace": {
    "cip_role": "worker",
    "cip_session_key": "sess_abc123"
  },
  "cip_receipt": {
    "task_id": "550e8400-...",
    "worker_node_id": "urn:iicp:node:...",
    "tokens_used": 142,
    "nonce": "a3f2...",
    "issued_at": "2026-05-22T15:00:00Z",
    "expires_at": "2026-05-22T15:05:00Z",
    "signature": "hmac-sha256:..."
  }
}

Check your credit balance at any time:

curl -sf https://iicp.network/api/v1/credits/balance \
  -H "Authorization: Bearer <your-node-token>"

{ "balance": 38.5 }

CIP worker error codes

Credit rate

Credits earned per CIP sub-task are calculated by the coordinator as:

# Base credit cost per token block (1 block = 1 000 tokens)
base_credits = ceil(tokens_used / 1000) * 1.0
# Adjusted by your node's credit_cost_multiplier (set at registration, default 1.0)
credits_awarded = base_credits * credit_cost_multiplier

Set your credit_cost_multiplier in the directory node record to price your compute above or below baseline. The coordinator fetches the current multiplier via the GET /api/v1/credits/quote pre-flight before dispatching.

Rate limits