---
title: "bot.desk-lease@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/bot.desk-lease"
updated: null
---

# bot.desk-lease@1 · OpenVibe.Services

HTML: [bot.desk-lease@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/bot.desk-lease)

# BotDeskLease `bot.desk-lease@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
- Decision: [ADR-043](/docs/adr/ADR-043)
- Schema: [`https://openvibe.network/contracts/bot/desk-lease.v1.json`](/docs/contracts/bot.desk-lease.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

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `machine_id` | string | yes |  | - `pattern ^dev_[0-9A-HJKMNP-TV-Z]{26}$` |
| `desk` | string | yes |  | - `pattern ^desk-[a-z0-9][a-z0-9-]{0,23}$` |
| `session` | `https://openvibe.network/contracts/run/session.v1.json#/$defs/session_id` | yes |  |  |
| `owner` | string | yes | The session's person, the only one whose commands reach the desk. | - `pattern ^user:usr_[0-9A-HJKMNP-TV-Z]{26}$` |
| `kind` | const | yes |  | - `= "browser"` |
| `width` | integer | yes |  | - `minimum 640`<br>- `maximum 3840` |
| `height` | integer | yes |  | - `minimum 480`<br>- `maximum 2160` |
| `shared` | boolean | yes | true on a desk host that serves other people (the desk runs in its own sandbox there); false on the person's own machine. |  |
| `created_at` | string | yes |  | - `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 }] }
~~~~