--- title: "bot.machine-pool@1 · OpenVibe.Services" canonical: "https://openvibe.services/docs/contracts/bot.machine-pool" updated: null --- # bot.machine-pool@1 · OpenVibe.Services HTML: [bot.machine-pool@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/bot.machine-pool) # BotMachinePool `bot.machine-pool@1` Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/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`](/docs/contracts/bot.machine-pool.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. | - `pattern ^pool_[0-9A-HJKMNP-TV-Z]{26}$` | | `owner` | string | yes | The person every machine in the pool belongs to. Pools of different owners are not allowed. | - `pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$` | | `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. | - `pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$` | | `machines` | array of object | yes | The members, head included, two to eight. | - `minItems 2`
- `maxItems 8`
- `items: no other fields` | | `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. | - `pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$` | | `machines[].owner` | string | yes | The machine's owner when it announced itself; it must equal the pool's owner. | - `pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$` | | `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. | - `pattern ^(10\.(25[0-5]\|2[0-4][0-9]\|1[0-9]{2}\|[1-9]?[0-9])\|172\.(1[6-9]\|2[0-9]\|3[01])\|192\.168)\.(25[0-5]\|2[0-4][0-9]\|1[0-9]{2}\|[1-9]?[0-9])\.(25[0-5]\|2[0-4][0-9]\|1[0-9]{2}\|[1-9]?[0-9])/([89]\|[12][0-9]\|30)$`
- `maxLength 32` | | `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. | - `maxLength 45` | | `machines[].port` | integer | yes | The TCP port of the machine's private link on \`address\`. | - `minimum 1024`
- `maximum 65535` | | `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. | - `minimum 0`
- `maximum 16777216` | | `machines[].free_ram` | integer | yes | Free system memory when it announced itself, in MB. | - `minimum 0`
- `maximum 16777216` | | `machines[].hardware` | string | yes | A short hardware name the fit table matches measured speeds on, such as x86\_64 or the GPU model. | - `maxLength 120` | | `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. | - `pattern ^-----BEGIN CERTIFICATE-----`
- `maxLength 8192` | ## 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 }] } ~~~~