BotDeskLease bot.desk-lease@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
Decision
ADR-043
Schema
https://openvibe.network/contracts/bot/desk-lease.v1.json

bot.desk-lease@1 (the Desks plan's D6): one desk OpenVibe.Bot holds for one OpenVibe.Run session, as POST /api/v1/machines/{id}/desk-leases answers it (201, capability bot.desk.session, a Run service token acting for the session's person in X-OV-Subject) and GET /api/v1/machines/{id}/desk-leases/{desk} reads it. The request is bot.desk-lease-create-request@1. Bot leases a desk only on the person's own machine where they turned on 'Let my agent use this computer' (shared false), or on a desk host whose owner offers its desks to other people and whose OpenVibe Link runs each desk in its own sandbox (describe desk.isolation sandbox; shared true). The lease starts the desk (bot.command@1 kind desk, start, kind browser, the lease's size) and from then on only the lease's person, through Run, may act on that desk, with screen, input and browser at POST /api/v1/machines/{id}/desk-leases/{desk}/commands (bot.command@1 without desk, answered by bot.command-result@1): never another desk, never the machine's own screen, files, programs or network, and on a shared host not even its owner's own commands reach a leased desk. DELETE /api/v1/machines/{id}/desk-leases/{desk} stops the desk and ends the lease; so does the machine going away (Run sees the lease gone, 404, and ends the session host_lost).

Fields

FieldTypeRequiredDescriptionConstraints
machine_idstringyes
  • pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$
deskstringyes
  • pattern ^desk-[a-z0-9][a-z0-9-]{0,23}$
sessionhttps://openvibe.network/contracts/run/session.v1.json#/$defs/session_idyes
ownerstringyesThe session's person, the only one whose commands reach the desk.
  • pattern ^user:usr_[0-9A-HJKMNP-TV-Z]{26}$
kindconstyes
  • = "browser"
widthintegeryes
  • minimum 640
  • maximum 3840
heightintegeryes
  • minimum 480
  • maximum 2160
sharedbooleanyestrue on a desk host that serves other people (the desk runs in its own sandbox there); false on the person's own machine.
created_atstringyes
  • format date-time

Examples

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

Valid: shared-host
{
  "machine_id": "dev_01J8Z4M2Q0R7T9YV3K6N8P1W2X",
  "desk": "desk-s0mnpqr",
  "session": "ses_01JD2C3D4E5F6G7H8J9K0MNPQR",
  "owner": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "kind": "browser",
  "width": 1280,
  "height": 800,
  "shared": true,
  "created_at": "2026-10-28T10:00:01Z"
}
Rejected: private-desk
{
  "machine_id": "dev_01J8Z4M2Q0R7T9YV3K6N8P1W2X",
  "desk": "private",
  "session": "ses_01JD2C3D4E5F6G7H8J9K0MNPQR",
  "owner": "user:usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "kind": "browser",
  "width": 1280,
  "height": 800,
  "shared": true,
  "created_at": "2026-10-28T10:00:01Z"
}
Rejected: service-owner
{
  "machine_id": "dev_01J8Z4M2Q0R7T9YV3K6N8P1W2X",
  "desk": "desk-s0mnpqr",
  "session": "ses_01JD2C3D4E5F6G7H8J9K0MNPQR",
  "owner": "service:run",
  "kind": "browser",
  "width": 1280,
  "height": 800,
  "shared": true,
  "created_at": "2026-10-28T10:00:01Z"
}

Validate

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