Building the HTTP for the Age of Generative AI
Protocol-suite release: v1.10.16
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.
The Open Intelligence Architecture Application Matrix currently lists this repository in its pending review band. The badge above reports an automated structural classification, not approval, certification or endorsement. See the IICP-to-OIA evidence map for the intended layer boundaries and links to the implementation evidence a reviewer can inspect.
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.
Official chat() helpers give compatible models a small, versioned IICP
runtime context by default. It explains that the model or service was selected
through IICP and is not IICP itself. The client includes the active intent and
its implementation version, then adds a model, effective-capability or bounded
selection fact only when the current route supplies it authoritatively.
Applications can disable the capsule or require a supported instruction
channel. Raw task submission, embeddings, transcription, MCP calls and other
non-chat operations are unchanged. The context is not an assistant persona, a
secret prompt or a prompt-injection defense. See the
runtime identity decision.
IICP's narrow role is intent resolution and provider eligibility/selection. It can select a policy-compliant provider before MCP, A2A, HTTP or another negotiated binding performs the task. It does not replace those execution protocols or the transports and security standards beneath them.
| Question | IICP | Adjacent protocol examples |
|---|---|---|
| How is the requested operation named? | Versioned Intent identifier plus constraints | A2A skills/messages and MCP tool, resource or prompt names describe different execution-layer concepts |
| How are usable service properties advertised? | Effective capabilities exposed by the complete service path | A2A Agent Cards and MCP server discovery describe their own execution or integration surfaces |
| Who applies eligibility and selects a provider? | Directory filtering plus client policy and final validation | A2A and MCP normally leave provider choice to the application; IAIP and AIDIP directly overlap this area |
| How is the task executed? | A negotiated binding | MCP, A2A, HTTP APIs and IICP peer framing can carry the selected task |
| What does the directory see? | Intent and bounded routing metadata, not the task payload | Depends on the adjacent protocol and deployment |
The comparison rates public evidence separately for specification precision, versioning, security, implementations, conformance, independent implementation, deployment and governance. It does not calculate a winner score. The chronology also separates the age of a protocol from the first public appearance of an overlapping mechanism.
This boundary has real overlap with current IAIP and AIDIP Internet-Drafts.
Review the selection and eligibility problem statement, the concise IICP protocol positioning
and the dated, source-backed
mechanism comparison before
making differentiation or standards claims. Internet-Drafts are work in
progress and are not IETF endorsement.
| 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.
| Project | Language | Integration surface | Status |
|---|---|---|---|
michaeloboyle/iicp-node-monitor |
Python | Local node events and health plus the public Directory Registry API | Independent community application; compatibility patch under upstream review |
Community integrations are maintained by their respective authors. They are not official SDK releases, protocol-conformance results, or evidence of support for every optional Profile. The node monitor was last reviewed against current public IICP interfaces on 21 August 2026; its upstream repository remains authoritative.
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.
IICP intent identifiers name what is being requested, independent of model or
backend. The deployed urn:iicp: form is preserved as a stable project-defined
identifier while formal namespace registration is pending:
urn:iicp:intent:<domain>:<action>:v<version>
Examples from registry/intents.json:
| Identifier | 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.
Published, deployed and observed versions are separate facts. The release map
in ecosystem/current-versions.json remains
the authority for published component versions. The additive
ecosystem version truth contract explains
how public evidence can report deployment and adoption without treating either
as a synonym for publication.
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 | The generated current-version projection is authoritative for package versions |
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 |
IICP is currently in Beta. You can join and test it if its current scope fits your use case.
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. Current maturation work includes:
- 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.
The immutable CHANGELOG.md is the release history. The
generated current-version projection records
the current protocol, implementation, package and browser axes without copying
those values into this overview. Compatibility claims are release-specific;
the current base-wire baseline is labeled at the top of this page.
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 accepted environmental-independence and extension architecture separates Core semantics from Profiles, Bindings, Registry entries and local implementation extensions. It preserves current connected operation while keeping transport, locator, timing, encoding and execution-backend choices out of Core.
The companion task time semantics keeps the current provider attempt budget separate from delivery lifetime, logical-task deadline, result validity and caller-local wait behavior.
The directory state semantics separate identity and advertisement validity from current reachability, execution availability and dispatch eligibility. Default discovery still returns only candidates that are eligible now.
The effective service capability semantics define capabilities as behavior exposed by the complete serving path. They separate modalities, features, runtime actions, limits, policy, Profiles, evidence, observations and evaluator-specific quality.
The architecture decision and documentation map shows how accepted decisions move from public rationale into normative contracts, implementation guides, and user-facing explanations without turning the website into a second specification.
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.
For an independent protocol or standards review, start with
standards/REVIEWING.md. The public
ecosystem/public-repositories.json
identifies the repositories and roles needed to continue implementation work.
The specification release and review-bundle procedures are reproducible from
public inputs and do not depend on the project's private development methods.
CONTINUATION.md explains how an independent implementation
or successor effort can preserve compatibility and release history.
| 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 |
The simulation-oriented tools use optional scientific dependencies. Install
them in an isolated environment with
python3 -m pip install -r tools/research-requirements.txt. They are historical
research aids, not normative conformance or release gates.