desktop

Desktop Config

Turn the screen capability on/off for an existing agent (owner only).

Enabling re-runs the per-plan desktop cap for seats accounts (402 with code=seat_limit, same shape as create). The flag only changes what the NEXT boot does: MARITIME_DESKTOP=1 lands in the injected env, maritime-init launches the desktop stack. If saved memory lacks the desktop drive, fc-manager stops the VM and performs an ordinary retained start.

There is no persisted "recreate on next wake" marker in the wake path — wake only recreates when a snapshot is genuinely unusable (plan 30 A1), and image/env changes take effect on the next reconstruction. So this applies the change exactly the way env-var edits do (routers/agents.py skill env): an ACTIVE agent is rebuilt through orchestrator.rebuild_agent (stop -> commit derived rootfs -> recreate with fresh env); a sleeping or stopped agent keeps its snapshot and the change lands on its next reconstruction, surfaced through the legacy requiresRestart field. Retained public restart does not apply this deferred configuration. Enabling also raises the agent's RAM/CPU floor to the desktop default (4 GiB / 2 vCPU) when it is below — a 2 GB VM runs the screen with ~300 MB free, which is one Chromium tab away from OOM. Larger allocations are left alone; disabling never shrinks (use the resize endpoint).

patch/api/agents/{agent_id}/desktop-config

Request

  • Base URL
    https://api.maritime.sh (the document declares no server; this is the origin it was published from)
  • URL
    https://api.maritime.sh/api/agents/{agent_id}/desktop-config
  • Auth
    HTTP bearer

Path parameters

agent_idstring required

Request body

enabledboolean required

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.