Building the HTTP for the Age of Generative AI
Protocol-suite release: v1.10.12
Wire compatibility baseline: v1.9.0
Reference implementation: iicp.network
Status: Project-normative beta suite; individual profiles retain their own status
IICP components are independently versioned repositories rather than Git
submodules. This repository remains authoritative for protocol semantics and
publishes the machine-readable ecosystem registry. See
IMPLEMENTATIONS.md for the official implementations,
their current visibility, maturity and ownership boundaries.
ecosystem/CURRENT_VERSIONS.md presents every
current release axis from the same machine-readable catalog.
No paid GitHub feature is required to build, test, implement or participate in the protocol.
The terms project-normative, stable, active draft, experimental
and externally ratified have distinct meanings. See
SPEC_STATUS.md. IICP has not been ratified by the IETF or
assigned a service port by IANA.
IICP is an open protocol that lets AI agents discover each other, negotiate capabilities, and route tasks across a distributed network — without any central broker owning the compute or controlling the data.
Agent A ──CALL──▶ IICP Node B ──▶ LLM Backend
▲
│ discovery
iicp.network
(directory only —
no payload passes through)
The directory (iicp.network) is bootstrap and discovery only and does not receive task
payloads. Tasks route to the selected execution node, whose operator can read the work it executes.
Current IICP-CX clients encrypt requests across the network and relays when a provider advertises
cx_public_key; this is transport confidentiality, not executor-blind inference or anonymity.
{
"task_id": "550e8400-e29b-41d4-a716-446655440001",
"intent": "urn:iicp:intent:llm:chat:v1",
"payload": { "messages": [{ "role": "user", "content": "Summarise this doc." }] },
"constraints": { "timeout_ms": 5000, "qos": "interactive" }
}An intent URN expresses what you want, not which model or endpoint to call. The network finds the best available node that can serve that intent, routes the task, and returns a structured response.
| Document | What it covers | Normative level |
|---|---|---|
| iicp-core.md | Wire format, 14 message types, required fields, error codes, security minimums | MUST |
| iicp-semantics.md | Intent routing, QoS tiers, node scoring, retry policy, circuit breaker | SHOULD / MAY |
| iicp-extensions.md | Billing, reputation, MCP binding, Cooperative Inference, post-quantum | MAY / future |
| Document | What it covers |
|---|---|
| iicp-dir.md | IICP-DIR: directory registration, heartbeat, discovery, peer exchange |
| iicp-mcp-binding.md | MCP ↔ IICP translation rules |
| node-capability-format.md | Capability object schema: intents, models, limits, availability |
| iicp-billing-extension.md | Credits, billing fields, receipt protocol |
| iicp-cbor-wire.md | Optional CBOR wire encoding (Phase 3, application/iicp+cbor) |
| Document | What it covers |
|---|---|
| IICP-core-phase1-profile.md | Phase 1 field subset — the minimum viable implementation |
| conformance-test-suite.md | 200+ machine-verifiable test IDs (DIR-, PROXY-, SEC-, CIP-, DIR-FED-*) mapped to REACH probes |
| validation-methodology.md | How to validate implementations; performance claim disclosure |
| iicp-v1.5-overview.md | What changed in v1.5; migration guide from v1.4.2 |
| Path | Contents |
|---|---|
| schemas/task.json | JSON Schema 2020-12 for IicpTask |
| schemas/nodelist.json | JSON Schema 2020-12 for NodeListResponse |
| registry/intents.json | Official intent URN registry |
| spec/intent-risk-taxonomy.json | Shared prohibited/high-risk/transparency/minimal intent classification fixture |
| spec/mcp-tool-risk-taxonomy.json | Shared MCP tool-risk and default-gating fixture |
| Path | Contents |
|---|---|
| spec/archived/IICP_draft_1.4.2.txt | Original monolithic Internet-Draft (archived) |
Read IICP-core-phase1-profile.md for the minimum field subset. A Phase 1 node must:
- Register —
POST /v1/registerwith{endpoint, region, capabilities[], limits} - Heartbeat —
POST /v1/heartbeatevery 30 s with{load, active_jobs} - Accept tasks —
POST /v1/task— validate UUID-v4task_id, intent URN,timeout_msbounds - Discover peers —
GET /v1/discover?intent=urn:iicp:intent:llm:chat:v1 - Return structured errors — never raw exceptions; always
{"error": {"code": "IICP-Exxx", ...}}
| Level | Documents to satisfy | Typical implementer |
|---|---|---|
| Core | iicp-core.md MUSTs only | Minimal node, embedded device |
| Phase 1 | Core + IICP-core-phase1-profile.md | Reference implementation |
| Phase 2 | Phase 1 + iicp-dir.md §3.6 (peers) | Mesh node |
| Phase 3+ | Phase 2 + billing/reputation extensions | Full CIP node |
Three official client SDKs (see the generated
current-version projection) implement
both sides of the protocol — the consumer (discovery, routing, retry, fallback, CIP
consumer) and the provider (iicp-node runtime with backend auto-detection, NAT
escalation, relay worker/server modes, and a built-in MCP gateway). All are open-source
and published:
| Language | Install | Package registry | Source repository |
|---|---|---|---|
| Python | pip install iicp-client |
PyPI: iicp-client | github.com/RobLe3/iicp-client-python |
| TypeScript | npm install @iicp/client |
npm: @iicp/client | github.com/RobLe3/iicp-client-typescript |
| Rust | cargo add iicp-client |
crates.io: iicp-client | github.com/RobLe3/iicp-client-rust |
No install at all? iicp.network/browser-node runs a real model in your browser (WebGPU) and queries the live mesh as an IICP consumer — with a connection console that shows every discover/dispatch wire step.
The SDKs are conformant reference clients — a good starting point for understanding the wire format in practice. Bug reports and PRs are welcome on each repository.
If you are connecting an autonomous agent rather than calling the API by hand, start with Connect an AI agent to IICP. It separates consumer discovery from provider registration and shows where MCP or A2A can carry the task after IICP selects a route.
A provider node should become reachable without router surgery. The SDKs escalate
automatically: direct endpoint → UPnP pinhole → IPv6 GUA → relay
auto-election from the directory (outbound bind; transport_method=turn_relay) →
Quick Tunnel (zero-account cloudflared; transport_method=external_tunnel) —
each rung tried only when the previous fails, each surfaced honestly in the node's
exposure_mode so discovery and scoring can see how a node is reached.
The protocol's normative choices are backed by simulation and analysis. The full research
record — credit economy & rate calibration, reputation/tier modelling, adversarial robustness
(FRAME8, REP, MESH), routing/multi-path selection, cryptographic trustworthiness, portable
operator identity, gamification anti-gaming, NAT traversal, and more — lives under
research/, indexed in research/RESEARCH.md.
These notes are published so the spec's decisions are externally verifiable: each major parameter (tier weights, credit schedule, decay floors, EMA α, etc.) traces back to a documented simulation or analysis. Found a flaw or have a better method? The research is meant to be challenged — open an issue.
The live reference implementation also keeps a public research summary at iicp.network/research. Treat live-network evidence, controlled validation, simulation and future research as different confidence levels; do not cite simulations as production measurements.
Intent URNs identify what is being requested, independent of model or backend:
urn:iicp:intent:<domain>:<action>:v<version>
Examples from registry/intents.json:
| URN | Purpose |
|---|---|
urn:iicp:intent:llm:chat:v1 |
Conversational LLM completion |
urn:iicp:intent:llm:embedding:v1 |
Text embedding / vector |
urn:iicp:intent:llm:summarise:v1 |
Document summarisation |
urn:iicp:intent:vision:describe:v1 |
Image-to-text description |
urn:iicp:intent:audio:transcribe:v1 |
Speech-to-text |
To propose a new intent, open an issue with the URN, domain justification, and example payload.
The directory scores nodes server-side at query time. Clients receive a pre-sorted list and may only filter (remove available=false nodes or those with open circuit breakers).
Phase 3 scoring formula (currently deployed):
score = 0.35 × availability_factor
+ 0.28 × (1 − normalized_load)
+ 0.18 × capacity_ratio
+ 0.09 × region_match
+ 0.10 × reputation_score
See iicp-semantics.md for full term definitions.
All IICP implementations MUST:
- Use TLS 1.3 minimum for all inter-node communication
- Validate
task_idas UUID v4 - Validate
intentagainsturn:iicp:intent:[a-z0-9:]+:v[1-9][0-9]* - Validate
timeout_msin range [100, 300 000] - Never log or expose
payloadcontent - Return structured errors only — no stack traces, no filesystem paths
See conformance-test-suite.md SEC-* test IDs for machine-verifiable checks.
Cooperative Inference and routing hardening (active)
The iicp.network directory is live and the client SDK
release line is recorded in the generated
current-version projection. Each SDK includes
the iicp-node provider runtime, so a participant can use the mesh first and
provide capacity later. Live node availability, installed-version adoption and
encryption evidence change over time; consult the
live stats page before treating any network
condition as current.
The mesh is usable for its current capabilities, while relay hardening, broader privacy evidence and public federation remain separate maturity gates. Remote execution still means the selected provider can read the task it executes.
| Feature area | Status | Notes |
|---|---|---|
| Core protocol — register / discover / route | ✅ Live | Current evidence is published on the live stats page |
| CIP coordinator (multi-node dispatch) | ✅ Implemented | Credit receipts, response integrity verification |
| Reputation scoring | ✅ Ratified | Tier structure (§5.1.1) + bootstrap floor (§5.1.2) ratified 2026-05-24 — normative |
| Published SDKs (Python / TypeScript / Rust) | ✅ Published v0.7.100 | Shared protocol baseline; see Client SDKs |
Node runtime (iicp-node) |
✅ Published | Ships inside every SDK (pip install iicp-client → iicp-node serve) |
| Relay transport for unreachable workers | ✅ Shipped (v0.7.56) | HTTP long-poll worker transport — browsers and CGNAT operators bind outbound to a relay-capable node; consumers route through path-scoped relay endpoints with zero client changes |
| Browser node (WebGPU, zero install) | ✅ Live | iicp.network/browser-node — runs a real model in the browser via WebLLM, queries the live mesh as an IICP consumer (with a wire-level connection console), and can serve into the mesh via a relay. First directory-listed browser node verified end-to-end on 2026-06-12 |
| Browser-consumable nodes (CORS) | ✅ Shipped (v0.7.56) | Every node endpoint answers CORS preflights — any https-exposed node can serve web-page consumers directly |
| Automatic NAT escalation incl. Quick Tunnel | ✅ Shipped (all 3 flavours) | Ladder: direct → UPnP → IPv6 → relay auto-election → zero-account Cloudflare Quick Tunnel fallback. Direct paths stay preferred; Quick Tunnel remains a low-friction bootstrap/fallback rather than a production availability promise |
| Signed event log + compliance attestation | ✅ Live | Every registration/heartbeat/eviction in a cryptographically signed log (federation bootstrap source); signed compliance attestation endpoint |
| Federation (Phase 6 groundwork) | 🟢 FED-READY-1 proven | Rust replica directory bootstraps from the PHP seed via snapshot + signed event tail |
| Operator identity (Ed25519 delegation) | 🟢 Phase A live | ADR-045 — operators sign a delegation binding their Ed25519 key to each node; the directory verifies + resolves a public operator_display_name in discovery. operator_pubkey is directory-private, never served. |
| Founder recognition | 🟢 Live | Time-gated founder ordinals (iicp-recognition §5.4) — #1 reserved for the maintainer, #2..N earned by genuine served nodes; dedicated non-federated signed chain |
Estimated progress toward closed beta: ~80%
The mesh works end-to-end, the SDKs are publicly installable with full three-language parity, and a browser tab can both consume the mesh and (via relay) serve into it. The remaining gaps before closed beta are:
- A standing public relay (the transport is built and verified; one reachable host activates browser/CGNAT serving for everyone)
- A portable operator identity wallet (so node identities survive machine changes)
- Security and authentication hardening to production standard
- Complete live SDK/key adoption and verified privacy receipts before strict fail-closed privacy wording
Follow this repo or iicp.network for announcements.
| Version | Date | Notes |
|---|---|---|
| v1.10.2 | 2026-08-01 | Additive pre-normative discovery evidence: health reasons, Gold progress, latency basis, SDK currency and aggregate operator diversity; no ranking change. |
| v1.10.1 | 2026-07-31 | Corrective immutable release: pins synchronized structured release metadata in the integrity manifest; no wire change. |
| v1.10.0 | 2026-07-31 | Adds authenticated replica decommissioning, credential invalidation, signed lifecycle propagation and same-DID reactivation. |
| v1.9.3 | 2026-07-31 | Corrective immutable release: records Rust directory v0.1.4 snapshot-bootstrap correction; no protocol wire change. |
| v1.9.2 | 2026-07-30 | Corrective immutable release: aligns the generated implementation index and SDK references with the released source/package state; adds a fail-closed version-truth check. |
| v1.9.1 | 2026-07-30 | Status/version governance and transport/IANA errata. Superseded by v1.9.2 because its bundled implementation index still reported the preceding release versions. |
| v1.9.0 | 2026-05-30 | Security-hardening normative content: per-heartbeat reputation delta cap (§11.2), audit-report griefing cap (§11.5). Directory drift closeout: AUDIT_REPORT endpoint, Public Stats schema, free-credit rules, NODELIST health_label/exposure_mode/public_key + transport fields; credit-endpoint / SCORE_UPDATE-snapshot / tier-enum reconciliations |
| v1.8.0 | 2026-05-25 | S.13 ephemeral-by-design federation (ADR-033): HEARTBEAT/SCORE_UPDATE/REPUTATION_UPDATE removed from federated event log; snapshot+event-tail bootstrap (GET /v1/snapshot); replica registration handshake |
| v1.7.0 | 2026-05-24 | §5.1.1 tier structure + §5.1.2 bootstrap floor ratified; all 13 Phase-5 research tracks closed; mesh-health compound metric live |
| v1.6.0 | 2026-05-23 | CIP receipt response integrity (TC-9c response_hash); framing spec stubs (CBOR/QUIC); 12 additional sub-protocol docs |
| v1.5.0-draft | 2026-05-15 | Spec split (core/semantics/extensions); 7 sub-protocol docs; 40 conformance test IDs; CBOR wire format |
| v1.4.2 | 2024 | Original monolithic Internet-Draft |
v1.5+ is wire-compatible with v1.4.2 — no message opcodes, field names, or error codes changed.
IICP components are published as dedicated repositories. The implementation registry records their authority, visibility, lifecycle and independently versioned releases.
The PHP directory is the current Genesis Seed implementation. The Rust directory is a pre-1.0 operator preview and the intended long-term successor, but publishing it does not move production traffic or deprecate PHP. The three SDK repositories provide consumer and provider runtimes; the browser-node repository provides the experimental browser implementation.
The protocol specification in this repository is the authoritative source for building interoperable implementations. Third-party implementations that conform to the spec (see conformance test suite) are fully compatible with the live network.
Directory implementations also share an implementation-neutral context and signed service-event ownership contract. Internal module or service placement cannot redefine public routes, event ownership, replication behavior or authorization.
The public evidence access profile lists the version, implementation, registry, conformance, release and live-runtime artifacts intended for non-browser retrieval. Static source evidence has a repository fallback; unavailable live state is reported as unavailable rather than inferred from source metadata.
- Bug reports / clarifications: Open an issue
- New intent URNs: Open an issue with URN, domain, and example payload
- Protocol proposals: Open an issue tagged
protocol-change - Conformance tests: PRs to
spec/v1.9/conformance-test-suite.mdwelcome
All normative language follows RFC 2119 / BCP 14.
| File | Purpose |
|---|---|
| tools/protocol_integrity_analysis.py | Analyses a spec file for internal consistency |
| tools/quick_validation.py | Quick syntax + field validation against v1.4.2 |