BotMachinePool bot.machine-pool@1
Generated at from
openvibe-contracts v0.419.0 and
openvibe-sdk v0.161.0.
- Version
- 1.0.0
- Owner
- bot
- Visibility
- first-party
- Status
- active
- Compatibility
- backward
- Schema
https://openvibe.network/contracts/bot/machine-pool.v1.json
bot.machine-pool@1 (the pooled machines design, 2026-11-06): several of one owner's machines on the same local network that serve one model together through llama.cpp RPC, `rpc-server` on the members and `llama-server --rpc` on the head. OpenVibe.Network holds the record: the owner proposes it on /machines (POST /api/v1/machine-pools, two to eight of their own machines and an optional head; the default head has the most free VRAM), and each machine reads it with its own Link token (GET /api/v1/link/self/pools/:id, network.link.self.manage) and approves it locally (POST /api/v1/link/self/pools/:id/approve with { certificate }). A machine's `certificate` is null until it approves on that machine: the Link generates an Ed25519 key there, keeps the private key, and uploads only its self-signed public certificate, which the other members pin for the pool's private link. A pool with any null certificate never serves. The record never carries a private key or a prompt. What a schema cannot say, Network and Link check at run time: the members are distinct and the head is one of them; every member has the pool's owner, today, through Bot; every member was seen from the same public address with a private address in the same subnet; the head's direct link probe to each member passes; each machine's certificate is its own; and any change of membership, owner, head or key revokes the pool, so all machines approve a new one. A machine that leaves (removed, signed out, a different owner) drops its link and its key at once.
Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
id | string | yes | The pool's id (ULID, Crockford base32). A pool is never edited: a change is a new pool with a new id. |
|
owner | string | yes | The person every machine in the pool belongs to. Pools of different owners are not allowed. |
|
head | string | yes | The machine that runs `llama-server --rpc`, sees the prompt and answers; it must be one of `machines`. The others receive tensors only. |
|
machines | array of object | yes | The members, head included, two to eight. |
|
machines[].id | string | yes | The machine (Bot's device id), resolved by Network from the machine's own node token, never taken from the body. |
|
machines[].owner | string | yes | The machine's owner when it announced itself; it must equal the pool's owner. |
|
machines[].address | string | yes | The machine's private IPv4 address and prefix on the local network (RFC 1918 only, a /8 to a /30), such as 192.168.1.2/24, configured on one of its own interfaces. The private link listens only here; never 0.0.0.0, loopback or a public address. |
|
machines[].public_ip | string | yes | The public address Network saw the announcement come from (never the body's claim). Every member must share it with the head. |
|
machines[].port | integer | yes | The TCP port of the machine's private link on `address`. |
|
machines[].free_vram | integer | yes | Free GPU memory when it announced itself, in MB. The head's default and each member's share of the pool's credits follow it. |
|
machines[].free_ram | integer | yes | Free system memory when it announced itself, in MB. |
|
machines[].hardware | string | yes | A short hardware name the fit table matches measured speeds on, such as x86_64 or the GPU model. |
|
machines[].certificate | string | null | yes | The machine's self-signed Ed25519 public certificate (PEM) for this pool's private link, or null until the machine approves the pool on itself. Never a private key. |
|
Examples
From the contract's own test fixtures: valid ones validate, rejected ones must fail.
Valid: approved-three-machines
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": "-----BEGIN CERTIFICATE-----\nMIIBRDCB96ADAgECAhQ1F6qS8nQmfA4Z1EQWbuTK6c+/CDAFBgMrZXAwGDEWMBQG\nA1UEAwwNT3BlblZpYmUtcG9vbDAeFw0yNjExMDcwMjE1NThaFw0zNjExMDQwMjE1\nNThaMBgxFjAUBgNVBAMMDU9wZW5WaWJlLXBvb2wwKjAFBgMrZXADIQBzzRaEd6ZR\nqYbsbYK3W8CCJPIAbsNTlIXZYgPEC9yf76NTMFEwHQYDVR0OBBYEFPiGTnP9vRST\nUlo0W1Eh0xcOxA49MB8GA1UdIwQYMBaAFPiGTnP9vRSTUlo0W1Eh0xcOxA49MA8G\nA1UdEwEB/wQFMAMBAf8wBQYDK2VwA0EAOlCHoX3ONMZYTHx4GSAlxP4EQase+99L\nGykZvgPSVDs2alKLXW5fBxvn7OcEJ3g/EMmk9iZ+AL+CmLxdcYBLCw==\n-----END CERTIFICATE-----\n"
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": "-----BEGIN CERTIFICATE-----\nMIIBRDCB96ADAgECAhRrJ/6HQgidfd9Sah9rLZOC0022ejAFBgMrZXAwGDEWMBQG\nA1UEAwwNT3BlblZpYmUtcG9vbDAeFw0yNjExMDcwMjE2MjRaFw0zNjExMDQwMjE2\nMjRaMBgxFjAUBgNVBAMMDU9wZW5WaWJlLXBvb2wwKjAFBgMrZXADIQBIJ8mF2e9W\nbILuPZQVwA2/LgC2VFtQAnpPDXExV2jXYaNTMFEwHQYDVR0OBBYEFKi5Za/SzebG\nkYOs4rzWz72zsM55MB8GA1UdIwQYMBaAFKi5Za/SzebGkYOs4rzWz72zsM55MA8G\nA1UdEwEB/wQFMAMBAf8wBQYDK2VwA0EAtZp/I6vCQ72SrCrQeH4QCz+sXqwnn24U\np9v1GeWXRE26rNmM3/ZQ4J9Vqmb/inSL5fMSKw9MJG+yZMShheRiDA==\n-----END CERTIFICATE-----\n"
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D3",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.22/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 8000,
"free_ram": 32000,
"hardware": "x86_64",
"certificate": "-----BEGIN CERTIFICATE-----\nMIIBRDCB96ADAgECAhQqwkAcayM2me9QLHZC1hfsr6SzhTAFBgMrZXAwGDEWMBQG\nA1UEAwwNT3BlblZpYmUtcG9vbDAeFw0yNjExMDcwMjE2MjRaFw0zNjExMDQwMjE2\nMjRaMBgxFjAUBgNVBAMMDU9wZW5WaWJlLXBvb2wwKjAFBgMrZXADIQDpnjnjucPk\nMQo1LhbrbSQyafLHqnODj0osY1fgTX0OnKNTMFEwHQYDVR0OBBYEFNhCSBHW/m2E\naFc9D6a7JI0pgTs8MB8GA1UdIwQYMBaAFNhCSBHW/m2EaFc9D6a7JI0pgTs8MA8G\nA1UdEwEB/wQFMAMBAf8wBQYDK2VwA0EA9/RQDBo4SEF1PnY2eSnS1TcK5pL/qQ2y\nnOXOtppCWn8tcnR4or3aIqO+Ie/8nhFQlkwCfSZ9tcc2JuZi2PGDDg==\n-----END CERTIFICATE-----\n"
}
]
}Valid: pending-approval
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: extra-field
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
],
"private_key": "not-permitted"
}Rejected: loopback-address
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "127.0.0.1/8",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: member-extra-field
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null,
"node_credential": "not-permitted"
}
]
}Rejected: missing-head
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: one-machine
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: private-key-as-certificate
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": "-----BEGIN CERTIFICATE-----\nthe PRIVATE KEY pasted here by mistake\n-----END CERTIFICATE-----\n"
}
]
}Rejected: privileged-port
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.21/24",
"public_ip": "203.0.113.7",
"port": 80,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: public-address
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "8.8.8.8/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Rejected: wildcard-address
{
"id": "pool_01J8Z3Q4R5S6T7V8W9X0Y1Z2P1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"head": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"machines": [
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D1",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "192.168.1.20/24",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 24000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
},
{
"id": "dev_01J8Z3Q4R5S6T7V8W9X0Y1Z2D2",
"owner": "usr_01J8Z3Q4R5S6T7V8W9X0Y1Z2A1",
"address": "0.0.0.0/0",
"public_ip": "203.0.113.7",
"port": 50053,
"free_vram": 12000,
"free_ram": 32000,
"hardware": "NVIDIA GeForce RTX 4090",
"certificate": null
}
]
}Validate
const contracts = require('openvibe-contracts');
contracts.validate('bot.machine-pool@1', value); // { valid, errors: [{ path, message }] }