The most concrete examples of TCP endpoints in KERI documentation appear in witness demonstration configurations. The GLEIF vLEI training materials document a three-witness demo network that uses TCP endpoints:

• Wan: Accessible at http://witness-demo:5642
• Wes: Accessible at http://witness-demo:5643
• Wil: Accessible at http://witness-demo:5644

These endpoints demonstrate how KERI witnesses expose network services for receiving establishment events and returning signed receipts. The sequential port numbering (5642, 5643, 5644) on the same host represents a common pattern for deploying multiple witness instances for educational purposes.

Direct Mode Communication

KERI's direct mode operational model, as documented in the demo tutorials, involves peer-to-peer communication over TCP connections. The demo scripts keri_bob and keri_eve illustrate this pattern:

Bob's configuration:

• Remote port (client): 5621 (default)
• Local port (server): 5620 (default)

Eve's configuration:

• Remote port (client): 5620 (default)
• Local port (server): 5621 (default)

These configurations create bidirectional TCP connections where each participant acts as both client and server, exchanging key events and receipts directly without intermediary witnesses. The demo logs show communication patterns like:

Rx 127.0.0.1:5621
Tx 127.0.0.1:5620

Indicating received (Rx) and transmitted (Tx) messages over the established TCP connections between localhost endpoints.

KERIA Agent Architecture

The KERIA (KERI Agent in the cloud) service architecture references TCP endpoints in its deployment model. The documentation describes KERIA exposing three separate HTTP endpoints on three separate network interfaces:

1. Boot Interface - Agent Worker initialization endpoint
2. Admin Interface - REST API for command and control operations
3. KERI Protocol Interface - CESR over HTTP endpoint for protocol interactions

While the specific implementation details use HTTP layered over TCP, the underlying network addressing relies on TCP endpoint mechanisms for establishing connections to these services.

OOBI Resolution Context

The Out-Of-Band Introduction (OOBI) mechanism, which provides discovery and validation of IP resources for KERI autonomic identifiers, frequently references TCP endpoints. An OOBI associates a URL with an AID, and these URLs commonly point to TCP-accessible services:

• Witness endpoints for receiving key events
• Watcher endpoints for monitoring key event logs
• Agent endpoints for delegated operations

The OOBI documentation notes that "discovery via URI, trust via KERI" - meaning while the initial network location discovery may use TCP endpoint URLs, the cryptographic trust establishment occurs through KERI's signature verification mechanisms independent of the transport layer.

Relationship to KERI's Transport-Agnostic Design

Protocol Layer Separation

KERI's architecture maintains strict separation between its cryptographic event verification mechanisms and the underlying transport layer. The KERI whitepaper and specifications emphasize that authenticity and integrity are established through digital signatures and CESR encoding rather than transport-layer security.

This design philosophy means:

• KERI events can be transmitted over TCP, UDP, HTTP, HTTPS, or other protocols
• The cryptographic verifiability of events does not depend on transport security
• TCP endpoints are an implementation choice rather than a protocol requirement

CESR Encoding Across Transports

The Composable Event Streaming Representation (CESR) protocol, which provides the encoding layer for KERI primitives, is designed to work across multiple transport mechanisms. CESR's dual text-binary encoding enables:

• Text domain transmission over TCP connections for human-readable debugging
• Binary domain transmission over TCP for compact, efficient data transfer
• Composability ensuring lossless round-trip conversion between domains

The CESR specification notes that primitives can be "streamed over TCP, UDP, or HTTP" while maintaining their cryptographic properties. TCP endpoints provide the reliable, ordered delivery that simplifies CESR stream processing compared to UDP's connectionless model.

Network Protocol Traces

The KERI demo documentation includes several network protocol traces that demonstrate TCP endpoint usage in practice. These traces show:

Event Exchange Patterns

Inception events establishing new AIDs are transmitted between TCP endpoints with CESR-encoded payloads:

{"v":"KERI10JSON...","t":"icp","d":"...","i":"...","s":"0",...}

Followed by cryptographic signature attachments in CESR format.

Rotation events demonstrating key management operations flow over the same TCP connections:

{"v":"KERI10JSON...","t":"rot","d":"...","i":"...","s":"1","p":"...",...}

Receipt exchanges where validators return signed acknowledgments of observed events:

{"v":"KERI10JSON...","t":"vrc","d":"...","i":"...",...}

Connection Logging

The demo logs show TCP endpoints from the perspective of a single node:

Rx 127.0.0.1:51612  # Received from remote endpoint
Tx 127.0.0.1:51612  # Transmitted to remote endpoint

This logging pattern demonstrates the bidirectional nature of KERI communication over TCP, where both participants send and receive events, receipts, and queries over established connections.

TCP in KERI's Security Model

Bare Metal TCP vs. Secured Channels

The glossary entry for "tcp-endpoint" specifically references "bare metal TCP" as one variant, distinguishing it from secured channel alternatives. This terminology acknowledges that:

Bare TCP provides:

• Reliable, ordered delivery of byte streams
• Connection state management
• No confidentiality or transport-layer authentication

Secured alternatives layered over TCP include:

• TLS/HTTPS for encrypted, authenticated channels
• QUIC providing similar guarantees with modern transport features
• WebSockets for bidirectional communication in web contexts

KERI's security model explicitly does not depend on transport-layer security. The protocol provides:

• Authenticity through digital signatures on every event
• Integrity through cryptographic digests in event chains
• Non-repudiation through controller signatures on establishment events

This "end-to-end verifiable" security model means TCP endpoints can be used in untrusted network environments, with cryptographic verification providing security guarantees independent of the transport channel.

Witness Network Communication

The KAWA (KERI's Algorithm for Witness Agreement) consensus mechanism, which coordinates witness receipts for identifiers operating in indirect mode, relies on witnesses communicating over network connections. While the specific transport is implementation-dependent, TCP endpoints provide the reliable delivery characteristics that simplify witness coordination:

• Ordered event delivery ensures witnesses process events in sequence
• Connection state management enables efficient receipt collection
• Reliable transmission reduces the complexity of handling dropped messages

Implementation Considerations

Port Selection and Configuration

The demo configurations show typical port selection patterns:

• 5620-5621 range: Direct mode peer-to-peer demo communication
• 5642-5644 range: Witness service endpoints
• Custom ports: Production deployments select ports based on network policies

The KERI Command Line Interface (kli) includes options for configuring TCP endpoint parameters:

-r REMOTE, --remote REMOTE    Remote port number for client connections
-l LOCAL, --local LOCAL        Local port number for server listening

This flexibility allows deployments to adapt to different network environments, firewall rules, and organizational policies.

Connection Management

The TCP session identification mechanism described in the glossary entry has implications for KERI implementations:

Connection pooling: Implementations may maintain persistent TCP connections to frequently-contacted witnesses or agents, reusing the same client address/port tuple for multiple KERI operations.

Load distribution: When multiple witnesses share the same network address but use different ports (as in the demo configuration), clients can distribute load by opening connections to different TCP endpoints.

Failover handling: If a TCP connection to a witness endpoint fails, clients must re-establish the connection and potentially resend events, relying on KERI's idempotent event semantics rather than TCP's stream guarantees.

Docker and Containerized Deployments

did:webs Resolver Example

The did:webs resolver documentation demonstrates Docker-based deployment using TCP endpoints:

docker run -p 7676:7676 gleif/did-webs-resolver:latest

This command maps the container's internal TCP port 7676 to the host's port 7676, creating a TCP endpoint accessible to external clients. The resolver service listens on this endpoint for HTTP requests that resolve did:webs identifiers to their corresponding KERI event streams.

KERIA Agent Containers

The KERIA architecture, when deployed in containers, exposes its three network interfaces through TCP endpoint mappings. This containerized approach enables:

• Network isolation: Separating boot, admin, and protocol interfaces
• Port forwarding: Mapping container internal ports to host TCP endpoints
• Service discovery: Using container networking to connect clients to agent TCP endpoints

RACK (Routing, Authentication and Confidentiality with KERI)

The RACK security gateway implementation demonstrates production-grade TCP endpoint usage:

docker pull --platform linux/arm64 healthkeri/rack:latest
docker run -p [host_port]:[container_port] healthkeri/rack:latest

RACK implements "zero-trust network access" using KERI protocol over TCP endpoints, supporting both linux/amd64 and linux/arm64 architectures. The documentation shows TCP endpoint configuration for:

• Healthcare application proxying
• KERI event verification at network boundaries
• Multi-architecture deployment across cloud and edge devices

Comparison to Other Service Endpoints

While the glossary defines tcp-endpoint as a specific type of service endpoint, KERI infrastructure uses various endpoint types:

HTTP/HTTPS Endpoints

Many KERI services expose HTTP(S) endpoints, which are layered over TCP but provide additional protocol semantics:

• RESTful APIs for KERIA agent operations
• OOBI URL resolution returning key event streams
• Witness query endpoints returning JSON-encoded events

These maintain TCP's connection-oriented, reliable delivery while adding HTTP's request/response patterns and HTTPS's transport encryption.

WebSocket Endpoints

The KERIA notification system uses server-sent events for streaming updates to clients, which may be implemented over WebSocket connections that are themselves built on TCP. This provides:

• Persistent bidirectional channels over a single TCP connection
• Efficient event notification without repeated connection establishment
• Browser-compatible streaming for web-based KERI clients

UDP-Based Alternatives

While not extensively documented in the provided sources, the CESR specification notes that primitives can be streamed over UDP as an alternative to TCP. UDP endpoints would sacrifice:

• Guaranteed delivery (requiring application-layer retransmission)
• Ordered delivery (requiring application-layer sequencing)
• Connection state (requiring stateless operation)

In exchange for:

• Lower latency (no connection establishment overhead)
• Simpler infrastructure (no connection state management)
• Multicast capabilities (for witness broadcasting scenarios)

Practical Usage in KERI Tutorials

SignifyTS Connection Tutorial

The GLEIF vLEI training materials include a controller connection tutorial that demonstrates establishing authenticated connections between two KERI controllers. While the tutorial uses the KERIA agent architecture, the underlying communication occurs over TCP endpoints:

Setup pattern:

1. Both controllers connect to KERIA agent TCP endpoints
2. Controllers exchange OOBIs containing agent endpoint URLs
3. Agent-to-agent communication occurs over TCP for event exchange
4. Receipt collection flows back through the TCP connections

The tutorial notes that "real-world deployments would typically involve separate KERIA instances," each with its own TCP endpoints, communicating across network boundaries.

Witness Pool Configuration

The witness training module demonstrates witness pool setup with explicit TCP endpoint configuration:

# Query witness KEL
curl http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha

This command queries a witness's TCP endpoint to retrieve its OOBI information, demonstrating how TCP endpoints serve as the network access points for KERI infrastructure services.

Local Development Workflows

The did:webs getting started guide describes a local command-line workflow for development that includes:

1. Starting a witness pool (each witness on a TCP endpoint)
2. Running the resolver service with configured TCP endpoint parameters
3. Testing OOBI resolution by connecting to resolver TCP endpoints

This workflow is described as "best for development and debugging" because TCP's reliable delivery and connection-oriented nature simplifies troubleshooting compared to production deployments with complex network topologies.

Relationship to KERI's Modes of Operation

Direct Mode Architecture

In direct mode, two KERI controllers establish peer-to-peer TCP connections for synchronous event exchange:

• Source controller connects to destination controller's TCP endpoint
• Destination controller validates received events cryptographically
• No witnesses or intermediary infrastructure required
• TCP's reliable delivery ensures event ordering

The training materials note this is "best for intermittent connections" where both parties are online simultaneously.

Indirect Mode Architecture

In indirect mode, witnesses provide persistent TCP endpoints that:

• Accept connections from controllers to receive events
• Accept connections from validators to serve KELs and receipts
• Maintain availability when controllers are offline
• Coordinate receipt collection across the witness pool

The witness network's TCP endpoints enable the asynchronous communication pattern that characterizes indirect mode operation.

Technical Limitations and Considerations

Connection State Overhead

TCP's connection-oriented nature imposes overhead compared to stateless protocols:

• Connection establishment (three-way handshake) adds latency
• Connection state consumes server resources (memory per connection)
• Connection termination (four-way handshake) requires additional messages

For high-throughput KERI applications with many ephemeral connections, this overhead may motivate alternative transport choices.

Head-of-Line Blocking

TCP's ordered delivery guarantee creates potential head-of-line blocking:

• If packet N is lost, packets N+1, N+2, etc. are buffered until N is retransmitted
• KERI's event sequencing already provides ordering guarantees
• TCP's ordering may be redundant for KERI's purposes

Modern alternatives like QUIC provide multiple streams over a single connection to mitigate this issue.

Firewall and NAT Traversal

TCP endpoints face standard challenges in complex network environments:

• Corporate firewalls may block non-standard ports (e.g., 5620-5644 range)
• NAT devices complicate peer-to-peer direct mode connections
• Load balancers must maintain session affinity based on client address/port tuple

KERI deployments must account for these infrastructure realities when configuring TCP endpoints for production use.

Conclusion

A tcp-endpoint in KERI represents a service endpoint using the Transmission Control Protocol, identified by the characteristic that TCP packets do not include session identifiers—instead, both endpoints identify sessions using the client's address and port number, requiring a lookup operation on an internal routing table for packet processing.

While TCP endpoints appear throughout KERI documentation—particularly in demo witness configurations, direct mode tutorials, and KERIA agent architectures—they represent implementation choices rather than fundamental protocol requirements. KERI's transport-agnostic design establishes security through cryptographic signatures and CESR encoding, allowing TCP endpoints to provide reliable, connection-oriented delivery without bearing responsibility for authenticity or integrity guarantees.

The practical examples show TCP endpoints primarily in educational contexts (demo witnesses at ports 5642-5644, direct mode peers at ports 5620-5621) and containerized deployments (KERIA agents, did:webs resolvers, RACK gateways). Production deployments select TCP endpoint configurations based on network topology, organizational policies, and infrastructure requirements while relying on KERI's cryptographic security model for trust establishment independent of the transport layer.