HMS / FIELD GUIDE / LINUX RELEASE 0.2.0

Your agent.
Its own workspace.

Installation, requirements and the boundaries of the session.

01 / INSTALL

Start with your usual client.

hms lets Claude Code and Codex operate browsers and desktop apps in a separate session. Install it from the official release endpoint:

curl -fsSL https://lavett.dev/hms/latest/install.sh | sh

The installer downloads hms, checks its SHA-256, creates a Python environment under ~/.local/share/hms, links ~/.local/bin/hms and registers with Claude Code and Codex. It never uses sudo. Then ask your agent for GUI work in plain words.

Read the installer before running it ↗ · Release checksums ↗

02 / SYSTEM REQUIREMENTS

Linux first.

Tested: CachyOS (Arch), KDE Plasma 6.8, Wayland. Other distributions are untested. Requires Python 3.12 or newer and the distribution’s packages for KWin, AT-SPI, PyGObject, D-Bus, NumPy, Pillow, websockets, Tesseract, bubblewrap, libei, PipeWire, Firefox, gcc and pkgconf.

The installer runs hms doctor to identify missing requirements and unsupported environments. Unprivileged user namespaces must be permitted; Ubuntu 24.04 and later restrict them by default. Snap Firefox is unsupported.

Claude Code or Codex must be installed and signed in.

macOS is in testing, not qualified for this release.

The experimental path uses Python 3.12+, Xcode command line tools and a setup script that creates a separate user session. It needs administrator setup and Accessibility and Screen Recording permission. Windows is not available.

03 / THE CONTAINED SESSION

Your desktop stays yours.

hms works in its own graphical session. It does not take over your screen, mouse or keyboard. The session, applications, screen stream and text recognition run locally.

On Linux it hides /home, your home wherever it is, /root, /mnt, /media, /run/media and /srv. The rest of the system, including disks mounted elsewhere, is visible read-only. ~/hms-exchange is the shared writable folder.

That view governs files, not services. Services your account can use—such as Docker, libvirt and the system’s D-Bus—remain reachable through their sockets and act with their own rights. Through them, a program can change files as your account could.

The session guards against accidental damage to your desktop. It is not a security boundary against deliberately malicious code.

04 / YOUR SIGN-IN & BILL

Use the sign-in you have.

hms uses Claude Code and Codex through their existing CLI sign-in. The model provider bills you directly; hms has no account, API key or usage allowance of its own.

The navigator stops when the CLI reports that your subscription has reached its limit. The step during which the limit is reached can still be billed as extra usage or purchased credits.

hms sends no data to Bruket. Your model provider receives what your agent and the navigator send through your CLI. Your provider’s policy continues to apply.

05 / REMOVE

When you’re finished.

Stop the session and remove the client integrations:

hms down && hms uninstall all

To remove installed software and local state as well, review those directories before running this destructive command. Preserve files you want to keep first.

rm -rf ~/.local/share/hms ~/.local/state/hms

For an experimental macOS installation, also run the supplied macos-session-teardown.sh with sudo to remove the hidden user and session.

06 / SUPPORT & LICENCE

Made by Bruket.

Questions or problems: support@bruket.co.

hms is open source under the Apache License 2.0. The name and official builds are covered by a trademark notice. The included KDE screencast protocol description keeps its LGPL 2.1 or later licence.