---
title: "network.machine@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/network.machine"
updated: null
---

# network.machine@1 · OpenVibe.Services

HTML: [network.machine@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/network.machine)

# NetworkMachine `network.machine@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: network
- Visibility: public
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/network/machine.v1.json`](/docs/contracts/network.machine.json)

network.machine@1: one machine of a person, as the network's machines hub shows it (plan L34, steps M2 and M4). A machine is a Bot device of kind machine: an OpenVibe Link install that paired with the person's account. Bot stays the registry underneath (the device id is its dev\_…); Network fronts it for the person and for apps the person consented. The roles are what the machine does for the network (the catalogue: network.machine-roles@1), and running is what it does right now. Nothing here is a secret: no credential, no hash, no address.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes | The machine's device id in Bot's registry (dev\_…). | - `pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$` |
| `principal_id` | string |  | The machine's node principal on Network (lnk\_…): the credential it holds. Absent for a machine Bot knows but Network has no principal for. | - `pattern ^lnk_[0-9A-HJKMNP-TV-Z]{26}$` |
| `name` | string |  | The name the owner gave it. Absent when they gave none. | - `maxLength 80` |
| `kind` | enum | yes | What the machine is, as Bot's device record says: onboard (the robot's own machine), bridge (a machine that drives a robot over the robot's own link), server (a machine that runs its owner's jobs). | - `one of "onboard", "bridge", "server"` |
| `os` | string |  | The operating system the Link reports (linux, darwin, windows). Absent until the machine has checked in. | - `maxLength 40` |
| `online` | boolean | yes | Whether the machine is connected to Bot right now. |  |
| `last_seen_at` | string |  | When the machine was last seen. Absent before its first check-in. | - `format date-time` |
| `node_version` | string |  | The OpenVibe Link version the machine reports. Absent until it has checked in. | - `maxLength 40` |
| `roles` | array of string | yes | What the machine does for the network: the ids from the catalogue (network.machine-roles@1). The owner sets these; the machine applies them at its next check-in. | - `unique items`<br>- `items: pattern ^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$` |
| `running` | array of object | yes | What the machine is doing right now, as a short list: its Codes jobs, its desks, the local models it serves and the robots it drives. | - `items: no other fields` |
| `running[].kind` | enum | yes |  | - `one of "codes.jobs", "desks", "models", "robots"` |
| `running[].count` | integer | yes |  | - `minimum 0` |
| `running[].label` | string |  | A short, plain description for the owner (the desk's name, the model's name). | - `maxLength 120` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: robot

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "kind": "onboard",
  "online": false,
  "roles": [
    "bot.robot"
  ],
  "running": []
}
~~~~

Valid: worker

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "principal_id": "lnk_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "name": "Kitchen server",
  "kind": "server",
  "os": "linux",
  "online": true,
  "last_seen_at": "2026-10-31T09:00:00.000Z",
  "node_version": "0.15.0",
  "roles": [
    "codes.worker"
  ],
  "running": [
    {
      "kind": "codes.jobs",
      "count": 2
    },
    {
      "kind": "models",
      "count": 1,
      "label": "llama3"
    }
  ]
}
~~~~

Rejected: bad-id

~~~~
{
  "id": "machine-1",
  "kind": "server",
  "online": false,
  "roles": [],
  "running": []
}
~~~~

Rejected: bad-role

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "kind": "server",
  "online": false,
  "roles": [
    "codesworker"
  ],
  "running": []
}
~~~~

Rejected: bad-time

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "kind": "server",
  "online": false,
  "roles": [],
  "running": [],
  "last_seen_at": "yesterday"
}
~~~~

Rejected: missing-running

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "kind": "server",
  "online": false,
  "roles": []
}
~~~~

Rejected: unknown-kind

~~~~
{
  "id": "dev_01JAB2C3D4E5F6G7H8J9K0MNPS",
  "kind": "laptop",
  "online": false,
  "roles": [],
  "running": []
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('network.machine@1', value);   // { valid, errors: [{ path, message }] }
~~~~