LocalAI/docs/content/reference/p2p-api.md

+++ disableToc = false title = "P2P API reference" weight = 22 url = "/features/p2p/" +++

LocalAI supports peer-to-peer (P2P) networking for distributed inference. The P2P API endpoints allow you to monitor connected worker and federated nodes, retrieve the P2P network token, and get cluster statistics.

For an overview of distributed inference setup, see Distributed Inference.

Endpoints

List all P2P nodes

• Method: GET
• Endpoint: /api/p2p

Returns all worker and federated nodes in the P2P network.

Response

Field	Type	Description
nodes	array	List of worker nodes
federated_nodes	array	List of federated nodes

Each node object:

Field	Type	Description
Name	string	Node name
ID	string	Unique node identifier
TunnelAddress	string	Network tunnel address
ServiceID	string	Service identifier
LastSeen	string	ISO 8601 timestamp of last heartbeat

Usage

curl http://localhost:8080/api/p2p

Example response

{
  "nodes": [
    {
      "Name": "worker-1",
      "ID": "abc123",
      "TunnelAddress": "192.168.1.10:9090",
      "ServiceID": "worker",
      "LastSeen": "2025-01-15T10:30:00Z"
    }
  ],
  "federated_nodes": [
    {
      "Name": "federation-1",
      "ID": "def456",
      "TunnelAddress": "192.168.1.20:9090",
      "ServiceID": "federated",
      "LastSeen": "2025-01-15T10:30:05Z"
    }
  ]
}

---

Get P2P token

• Method: GET
• Endpoint: /api/p2p/token

Returns the P2P network token used for node authentication.

Usage

curl http://localhost:8080/api/p2p/token

Response

Returns the token as a plain text string.

---

List worker nodes

• Method: GET
• Endpoint: /api/p2p/workers

Returns worker nodes with online status.

Response

Field	Type	Description
nodes	array	List of worker nodes
nodes[].name	string	Node name
nodes[].id	string	Unique node identifier
nodes[].tunnelAddress	string	Network tunnel address
nodes[].serviceID	string	Service identifier
nodes[].lastSeen	string	Last heartbeat timestamp
nodes[].isOnline	bool	Whether the node is currently online

A node is considered online if it was last seen within the past 40 seconds.

Usage

curl http://localhost:8080/api/p2p/workers

---

List federated nodes

• Method: GET
• Endpoint: /api/p2p/federation

Returns federated nodes with online status. Same response format as /api/p2p/workers.

Usage

curl http://localhost:8080/api/p2p/federation

---

Get P2P statistics

• Method: GET
• Endpoint: /api/p2p/stats

Returns aggregate statistics about the P2P cluster.

Response

Field	Type	Description
workers.online	int	Number of online worker nodes
workers.total	int	Total worker nodes
federated.online	int	Number of online federated nodes
federated.total	int	Total federated nodes

Usage

curl http://localhost:8080/api/p2p/stats

Example response

{
  "workers": {
    "online": 3,
    "total": 5
  },
  "federated": {
    "online": 2,
    "total": 2
  }
}

Error Responses

Status Code	Description
500	P2P subsystem not available or internal error