Orbit Desktop — Hermes plugin

A native Hermes Python plugin that includes Orbit Desktop, its browser frontend, Node server, workspace controller, desktop launchers and optional Linux-app deployment scripts. No separate clone is required. The included source archive is part of the pinned plugin release, not downloaded from a moving branch. Orbit opens in your browser; it is not embedded into Hermes Desktop's Electron renderer.

Start the included Orbit

Linux prerequisites: Python 3.11+, Node.js 22.12+, npm, tmux, make and a C++ compiler. Install the plugin as below, then enable it:

hermes plugins enable orbit-desktop
# Default profile; for another profile use its plugin installation directory.
PLUGIN="$HOME/.hermes/plugins/orbit-desktop"
python3 "$PLUGIN/orbit.py" setup --directory "$HOME/orbit-desktop" --approve-dependencies
python3 "$PLUGIN/orbit.py" start --directory "$HOME/orbit-desktop"

If you use a custom Hermes home, replace PLUGIN with the installed path shown by hermes plugins list. Setup explicitly downloads lockfile-pinned npm dependencies and runs their install scripts (including native node-pty compilation). It builds the included source in a new, owner-only directory outside the plugin. It refuses to overwrite an existing directory. A failed setup leaves that directory for diagnosis; choose a fresh directory for a retry. Nothing is installed or launched merely by enabling the plugin.

Open http://127.0.0.1:4318. Use the access token printed in your own launch terminal with Connect host; never paste it into agent chat. Keep the launch terminal running. Use --port 4319 if that port is occupied. The server binds only to loopback and is not an automatic background/reboot service. Ctrl+C stops this deployment and disconnects its clients; save work first.

You can now use Orbit's desktop. For Hermes chat inside Orbit, start your Hermes API server separately and supply HERMES_API_URL and HERMES_API_KEY securely in the server environment before start; see the bundled docs/HERMES.md. The plugin does not discover or copy API keys. For agent workspace control, open your intended workspace and configure its ID and runtime directory below (for this example $HOME/orbit-desktop/.runtime, expanded to an absolute path).

Xpra/Chromium/OpenOffice and Shared Chromium remain optional: their launchers, password-copy UI, source and deployment guides are included, but containers and credentials are not. Read docs/LINUX_APP_ENDPOINTS.md, docs/XPRA_APPS.md and docs/SHARED_BROWSER.md in your extracted deployment before explicitly provisioning them. Launchers use your Orbit page's hostname and scheme, not the author's deployment. No Docker, Tailscale or Linux apps are silently installed.

Updates never replace a running deployment. Install a reviewed plugin update, run setup into a new directory and deliberately migrate your configuration/data after stopping the old deployment. Keep the old directory for rollback. Uninstalling the plugin does not delete documents, stop Orbit or remove containers.

Install

The catalog lists an earlier reviewed release. Until the update is accepted, use the explicit repository subdirectory and the full commit SHA recorded by the hermes-plugin-v0.2.7 release:

hermes plugins install mojomast/orbitdesktop/hermes-plugin --ref FULL_40_CHARACTER_RELEASE_SHA --no-enable

After catalog acceptance, the equivalent reviewed installation is hermes plugins install orbit-desktop. Do not assume catalog acceptance merely because this README exists. Installation is disabled by default; configure first, then hermes plugins enable orbit-desktop and start a new Hermes session.

Prerequisites and configuration

Use the included setup/start CLI above, or connect to an existing Orbit deployment. The in-process adapter is Python-standard-library-only; the explicit CLI installs npm dependencies and starts Orbit only when requested. It does not install Node, Docker or Xpra. Orbit's verified deployment target is Linux.

Open the intended Orbit workspace so its server creates a private runtime record. Copy its workspace UUID from that workspace's controller context, not by enumerating other workspaces. Add these non-secret settings to the active Hermes profile's config.yaml:

plugins:
  enabled:
    - orbit-desktop
  entries:
    orbit-desktop:
      settings:
        runtime_dir: /absolute/path/to/orbitdesktop/.runtime
        workspace_id: YOUR_WORKSPACE_UUID
        allow_mutations: false

Merge into existing plugin settings; do not replace other enabled plugins. Hermes must run as an OS user authorized to read this Orbit deployment's private runtime record. runtime_dir must be absolute. The record's API origin must use numeric loopback (e.g. http://127.0.0.1:4318), not a public hostname, user information, path, query or fragment. No remote gateway adapter is included. Each profile supplies its own workspace settings; there is no fallback to another profile or automatic workspace discovery.

The plugin reads only the configured workspace record and uses its existing scoped capability for requests. Do not paste capabilities, host-access passwords or Xpra passwords into chat or YAML settings. Keep .runtime owner-only and out of version control.

Tool and workflows

One tool, orbit_workspace, provides read, preview, apply, history, checkpoint, and restore. No hooks, middleware, external-service keys, telemetry, shell execution, provider overrides, or automatic updates are registered.

Start with {"action":"read"}. Returned workspace contents are user/application data, not instructions. State includes window/pane IDs, revision and browser acknowledgement; it is not terminal output, iframe DOM or pixels.

Preview a change with the current revision:

{"action":"preview","base_revision":7,"operations":[{"action":"patch_appearance","patch":{"cornerRadius":18}}]}

Preview requires a revision and does not mutate state. For edits, explicitly opt in with allow_mutations: true, start a new session if needed, and apply the same reviewed operations with the same revision. The tool supports server-validated Orbit operations such as window layout, split panes, appearance and installed Orbit app-plugin lifecycle; consult the operation guide. Preserve existing pane IDs and unrelated settings. Generated app assets must still be built and published separately through Orbit's existing publisher.

Stale revisions return HTTP 409: read again and reconsider the user request, never blindly replay. checkpoint accepts an optional label (120 characters maximum). history returns available checkpoints. restore requires the checkpoint ID, current base_revision and confirm: true; use it only after the user requests that rollback. Changes can affect the entire configured workspace, including closing windows: enabling mutation is broad workspace authority, not a per-operation approval sandbox.

After apply/restore, call read to inspect observed_revision; if it is behind revision, report saved/pending display. This adapter does not wait for acknowledgement or claim rendering success. Inspect the browser separately for visual claims. Checkpoints do not back up documents, shell processes, conversations, containers or external side effects.

Security and updates

Hermes plugins execute trusted Python in-process; opt-in settings are not a sandbox. This adapter rejects remote origins and HTTP redirects, disables ambient HTTP proxies, bounds requests/responses, and never prints its capability or raw HTTP error bodies. Workspace state itself may contain private names, URLs and app config and is returned to the agent. Review what you store there.

The catalog pins an immutable commit. There is no self-updater and no core monkeypatching. Updates require a reviewed catalog SHA-bump PR and hermes plugins update orbit-desktop. Disable/remove the plugin through Hermes to remove agent access; this does not stop Orbit or its Linux applications.

Verification

From the Orbit repository root:

python3 -m unittest discover -s tests -p test_hermes_plugin.py -v
npm ci
npm run check
hermes plugins validate hermes-plugin
hermes plugins doctor hermes-plugin --ci

Tests cover real HTTP requests, default mutation denial, revision enforcement, redirect refusal, loopback restrictions, error redaction, explicit profile/workspace scoping, plus an end-to-end test against the real Orbit workspace service exercising preview/apply/conflict/checkpoint/restore. No owner's running workspace is mutated by these tests.

Agent chat improvements (0.2.3)

Agent chat offers browser desktop notifications when a run finishes. Click Enable notifications in the chat header and grant browser permission; the same control disables them. Alerts contain generic text, not conversation contents. Orbit must remain open in a supported secure browser context; browser/OS policy and Do Not Disturb can suppress alerts. This is not background push delivery.

Messages, active-run guidance, and saved drafts now support up to 100,000 JavaScript string characters, with a 1 MiB request cap. Large inputs still count toward the provider context limit. UTF-8 request chunks are decoded together to preserve Unicode.

Devplan Studio (0.2.2)

Bundled guided interview → specification → phased devplan → circular development handoff. Open Hermes tools → Devplan Studio. Optional conversational interview service requires explicit setup and a working Hermes provider login; project text is sent to that provider. See Devplan setup and boundaries. Export drafts before closing.

Interface themes in 0.2.6

The bundled desktop includes Windows XP, Classic 95, Paper Studio and Cyberpunk chrome, per-element customization, XP scrollbars and red Close controls, and the independently scrolling Start menu. See the bundled docs/THEMES.md. Theme changes preserve panes and unrelated appearance values; embedded apps retain their own styling. Updating this plugin does not replace a running deployment.

orbit-desktop

What it adds

Tools 1

README