Documentation

Everything you need to get Leassh running. From one-click family setup to self-hosted fleet management.

Quick Start

Leassh runs on your network — your monitoring data never leaves it. One binary, one YAML file.

Step 1: Install the server

Download the release for your OS from github.com/cgoberg/releases, or install the Home Assistant add-on for the one-click tier.

Step 2: Point it at your machines

Add each machine to fleet.yaml. You can monitor over SSH, or install the agent on the machine for outbound-only connectivity.

nodes: - name: kids-pc host: 192.168.1.131 ssh: monitoring@192.168.1.131 os: windows

Option A: Install the agent (recommended)
Install the lightweight Leassh agent on each device. Enter a pairing code and it connects automatically. Works through firewalls and NAT.

Windows (PowerShell as Admin) powershell -ExecutionPolicy Bypass -Command "& { $env:LEASSH_TOKEN='YOUR_TOKEN'; iwr -useb https://leassh.com/install-windows.ps1 | iex }"
Linux curl -fsSL https://leassh.com/install.sh | sudo LEASSH_CODE='YOUR_CODE' bash
macOS (Apple Silicon) curl -fsSL https://leassh.com/install.sh | sudo LEASSH_CODE='YOUR_CODE' bash

Replace YOUR_CODE with the pairing code from your dashboard. For detailed platform-specific instructions, see the Install page.

Option B: SSH Probing (no install on targets)
Add machines to fleet.yaml with their SSH details. Leassh probes them directly. Nothing installed on the monitored machines. Requires SSH key access. See Self-Hosting for details.

Step 3: Add your license

Paid subscription licenses are online LSH-… keys validated through leassh.com with a 72-hour local cache. Offline LSH1.… Ed25519 tokens remain available for paid installations that need them. Free is an online 2-computer license issued at registration and works through the same path. See Plans and licensing.

Step 4: See it everywhere

The Home Assistant integration turns every node into a device with presence, load, and safe action buttons; the OpenClaw plugin exposes the same fleet to your agent; anything with HTTP speaks the REST+WS API below.

Plans and licensing

One catalog, four plans. Prices and limits are the same everywhere on the site and in the server entitlement table.

PlanComputersAnnual / moMonthlyTrial
Free2$0$0—
Family10$9.99$14.9914 days
Pro25$19.99$29.9914 days
UnlimitedUnlimitedContact—

Free includes the local dashboard, Home Assistant integration, sensors, binary sensors, presence, curated buttons, notify, Assist, basic alerts and one ha API token. Family adds AI screen analysis, weekly reports, screen time, limits/enforcement, content alerts, and Telegram/email channels. Pro adds the fleet dashboard, rules, webhooks, MQTT, SSH actuation, the full REST API and OpenClaw, for 25 computers. Unlimited adds unlimited nodes, priority support and multi-site onboarding.

API tokens are declared under api.tokens. Free accepts exactly one token, and the documented primary scope is ha. Using Home Assistant and OpenClaw at the same time requires Family or Pro. The former entry tiers are retired; their IDs are accepted as legacy IDs mapped to Family for 90 days.

Connection Modes

Leassh supports two ways to connect machines. Both provide the same monitoring data.

AgentSSH
Install on targetYes (tiny service)No
Setup difficultyEnter pairing codeConfigure SSH keys
Works through firewallsYes (outbound only)Needs inbound SSH access
Screenshot capabilityYes (with macOS permission)Yes (with macOS permission)
Remote command executionPaid only (tunnel mode)Yes
Best forDesktops, laptops, remote machinesServers, NAS, VMs

Deploy Agents via SSH

If you already have SSH access to a machine, you can deploy the agent remotely without physically touching the machine:

Linux ssh user@192.168.1.100 "curl -fsSL https://leassh.com/install.sh | LEASSH_CODE=YOUR_CODE sudo bash"
Windows (PowerShell) ssh user@192.168.1.100 "powershell -Command \"& { $env:LEASSH_CODE='YOUR_CODE'; iwr -useb https://leassh.com/install-windows.ps1 | iex }\""
macOS ssh user@192.168.1.129 "curl -fsSL https://leassh.com/install.sh | LEASSH_CODE=YOUR_CODE sudo bash"

macOS Note: After deploying the agent on a Mac, the Screen Recording permission must be approved once from the machine's physical keyboard. Open System Settings → Privacy & Security → Screen Recording and enable “Leassh Capture”. This is a one-time step required by Apple — no software can bypass it. All other monitoring features work immediately without this step.

Self-Hosting

Run everything on your own hardware. Zero data leaves your network.

Option A: Binary (recommended)

Download the server binary from GitHub Releases and run it directly:

Linux x64 curl -L https://github.com/cgoberg/releases/releases/latest/download/leassh-server-linux-x64.tar.gz | tar xz ./leassh fleet.yaml

Option B: Docker

The container image is hosted on GitHub Container Registry. Authenticate first:

docker-compose.yml docker login ghcr.io # GitHub username + personal access token version: "3.8" services: leassh-server: image: ghcr.io/cgoberg/leassh:latest ports: - "8383:8383" volumes: - ./fleet.yaml:/app/fleet.yaml

Requirements

Configuration Reference

Leassh is configured via fleet.yaml. Here are the key sections:

Nodes

Define the machines in your fleet:

nodes: - name: kids-pc host: 192.168.1.50 ssh: user@192.168.1.50 permissions: screenshot: true process_list: true enforce: true - name: gpu-server host: 192.168.1.100 ssh: admin@192.168.1.100 gpu: nvidia

Screen Time

KeyTypeDefaultDescription
enabledboolfalseEnable screenshot capture and activity classification
capture_interval_minutesint10Minutes between screenshot captures
data_retention_daysint30Days to keep activity data before auto-purge
vision.ollama_urlstring—URL of your Ollama instance for local AI
vision.modelstringllavaVision model to use for screenshot analysis

Time Limits

KeyTypeDescription
nodestringWhich node this limit applies to
categorystringActivity category (gaming, social_media, etc.)
max_minutes_per_dayintMaximum allowed minutes per day

Rules

KeyTypeDescription
namestringUnique rule identifier
whenstringCondition expression (supports time, metrics, processes)
nodeslistWhich nodes the rule applies to
actionslistActions: notify, ssh_command, kill_blacklisted, kill_category

Notifications

notifications: telegram: bot_token: "your-bot-token" chat_id: "your-chat-id" webhook: url: "https://your-webhook.com/alert"

OpenClaw Plugin

The openclaw-fleet plugin connects your Leassh fleet to any OpenClaw-compatible AI agent. Ask natural language questions about your infrastructure and get real-time answers.

Install the plugin git clone https://github.com/cgoberg/openclaw-fleet.git cd openclaw-fleet pip install -r requirements.txt

v0.2.0 adds server mode: pair the plugin with a Leassh server ({"mode": "server", "serverUrl": "…", "apiToken": "…"}) instead of spawning a local binary — same tools, one fleet authority. Standalone mode now mDNS-probes and warns before running a second authority.

Once installed, you can ask your AI agent things like:

See the openclaw-fleet repository for full setup instructions and configuration.

API Reference

One dialect, multiple transports: the same JSON-RPC vocabulary over stdio, REST, and WebSocket. Scoped tokens (forge · ha · openclaw · admin) are minted in fleet.yaml; the HA scope structurally cannot execute commands.

REST

GET  /api/health                  # liveness + license banner (public)
GET  /api/devices                 # bulk fleet state (ETag/304)
GET  /api/devices/{id}            # node detail
POST /api/devices/{id}/action     # curated verbs: reboot_node, sign_out_session
POST /api/notify                  # {source, level, title, body, ack_url?}
GET  /api/actions                 # the curated verb catalog

WebSocket

ws /api/ws  -> hello {token, protocol_version: 1}
            <- welcome + correlation-id RPC (same methods)
            <- {method: "leassh_event", params: {kind, data, ts}}

Events: node.online/offline/activity, trigger.*, notify, action.*. The server advertises _leassh._tcp via mDNS for discovery.

Home Assistant

The Home Assistant integration is included on every plan, including Free. Add cgoberg/leassh-integration as a custom repository in HACS, or use the HAOS add-on which installs and pairs everything automatically. Every fleet node becomes a device — presence, signed-in, CPU, RAM — with curated action buttons and urgent notifications as iOS critical alerts through your own HA.

Free contract: 2 nodes, the local dashboard, sensors, binary sensors, presence, curated buttons, notify, Assist, and exactly one ha API token. A third node is rejected with a clear NODE_LIMIT_REACHED error; existing nodes keep reporting if a downgrade leaves you over the limit. License errors surface as an HA repair (license_invalid, license_expiring, or node_limit_reached) rather than “cannot connect”.

The add-on accepts both online LSH-… keys and offline LSH1.… tokens. Its working directory is /config/leassh, so data/license_cache.json and screen-time data survive restarts.

FAQ

Common questions are answered on the main site FAQ section. Here are some additional technical questions:

Does Leassh require open inbound ports?

No. The agent communicates outbound to your Leassh server. No inbound ports need to be opened on monitored machines. For self-hosted setups, you need the server to be reachable from agent machines on your LAN.

Can I run Leassh without Ollama?

Yes. Without a vision model, Leassh still captures process lists and system metrics. Screenshot classification will be disabled, but time limits based on process names still work.

What happens if the agent loses connection?

The agent buffers data locally and syncs when the connection is restored. Screen time enforcement continues to work offline based on the last known rules.

Can I monitor machines outside my LAN?

Yes. With the agent installed, machines connect outbound through any firewall or NAT. With SSH probing, use SSH tunneling or a VPN to reach machines outside your LAN.

Do I need to install software on the computers I'm monitoring?

You have two options. The recommended approach is to install the tiny Leassh agent (under 10MB) — just enter a pairing code and it connects automatically. Alternatively, power users can use SSH probing which requires no software on target machines but needs SSH access configured. Both give you the same monitoring data.