P2P API

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