Skip to content

README.md

Latest commit

 

History

History
209 lines (148 loc) · 6.77 KB

README.md

File metadata and controls

209 lines (148 loc) · 6.77 KB
Raw

LocalHive Agent

LocalHive Agent is the worker-side desktop application of LocalHive. It runs on a local machine, registers that machine with the LocalHive Master, reports worker availability through heartbeat messages, lets the user choose how much RAM is shared with the swarm, and supports a Pause/Resume mode for personal use of the machine.

The Agent is a desktop application with a JavaFX dashboard and System Tray integration. It stores the Worker API key outside config.json through a platform credential backend when one is available.

The Agent currently includes the initial Task Protocol path with NO_OP execution and constrained Docker workload execution. Broader workload types remain future work.

Current Capabilities

Implemented:

  • Local JavaFX dashboard with TilesFX resource tiles and Ikonli icons.
  • System Tray lifecycle: close-to-tray when supported, Open Dashboard, Pause/Resume, and controlled Exit.
  • Local configuration stored under <user-home>/.localhive-agent/config.json.
  • Worker registration with the Master.
  • Shared RAM allocation update.
  • Hardware specification update based on OSHI-detected machine data.
  • Automatic heartbeat startup when Master URL, Worker ID, and API key are configured.
  • Manual heartbeat controls for diagnostics.
  • Gamer Mode through Pause/Resume with rollback on failed Master update.
  • Central AgentStateStore used by the dashboard and tray.
  • Task polling with NO_OP execution, local task history, constrained Docker workload execution, workspace inputs, and output artifact upload.
  • Native or platform-aware API key storage: Windows DPAPI, Linux Secret Service, macOS Keychain, and an explicitly insecure local fallback.
  • Local bounded file logging with representative secret sanitization tests.
  • Cross-platform GitHub Actions CI for Ubuntu, Windows, and macOS.

Planned:

  • Current Workload display.
  • Broader process execution.
  • Minecraft server workloads.
  • RCON/native packaging work described by the broader LocalHive ADR.

Technology Stack

The main runtime stack is:

  • Java 21
  • JavaFX
  • Maven
  • OSHI
  • Jackson 3 (tools.jackson.*)
  • JNA
  • TilesFX
  • Ikonli
  • SLF4J Simple
  • JUnit 5

Versions are managed in pom.xml.

Requirements

  • JDK 21
  • Maven
  • Git

Platform credential requirements:

Platform Expected backend Notes
Windows DPAPI Uses the current Windows user profile.
Linux Secret Service Requires secret-tool, a usable desktop keyring, and an active session that can access it.
macOS Apple Keychain Uses the Apple Security Framework through JNA. Real Keychain behavior still needs manual verification on physical macOS hardware.
Fallback Local file Explicitly marked insecure and used when no supported secure backend is available.

System Tray support depends on the desktop environment. Some Linux desktops, WSL sessions, Wayland setups, and headless environments may not support it.

Build And Run

Build and test:

mvn clean verify

Run the desktop application during development:

mvn javafx:run

The Maven JavaFX plugin starts:

dev.adrian.goral.localhiveagent/dev.adrian.goral.localhiveagent.app.Launcher

Configuration

The Agent stores local configuration in:

<user-home>/.localhive-agent/config.json

On Windows this is the same user.home based location, using Windows path separators.

Current config fields:

{
  "masterBaseUrl": "<master-url>",
  "workerId": "<worker-id>",
  "sharedRamMb": 8192,
  "pauseEnabled": false,
  "docker": {
    "enabled": true,
    "allowedImages": [
      "alpine:3.20"
    ],
    "maxMemoryMb": 4096,
    "maxCpuCores": 8,
    "allowGpu": false
  }
}

The API key is not stored in config.json. It is stored through the selected CredentialStore.

Docker Policy

Docker policy is a local Agent security policy. The Master can assign a Docker workload, but the Agent runs it only when the local policy allows the requested image and resources. Docker workloads may optionally mount a small read-only workspace artifact at /workspace and always receive an Agent-generated writable /output directory for output artifacts.

See docs/docker-policy.md for the current Docker workload V1 limits, failure codes, and future extension path. See docs/workspace-artifacts.md for the current workspace artifact flow. See docs/output-artifacts.md for the current output artifact flow. See docs/execution-display-metadata.md for execution display names used by claim, current execution, and task history views. See docs/capability-reporting.md for heartbeat capability reporting.

Credential Storage

Platform Backend Secure
Windows Windows DPAPI Yes
Linux Linux Secret Service Yes
macOS macOS Keychain Yes
Fallback Insecure file storage No

See docs/security.md for the security model and limitations.

Logs

Local logs are stored under:

<user-home>/.localhive-agent/logs

The default policy keeps approximately 50 MiB of managed logs:

  • 10 MiB per file.
  • 5 files maximum.

Logging mirrors console output to bounded local files when file logging can be initialized. If file logging fails, the console remains available.

See docs/security.md for logging security notes.

System Tray

When SystemTray.isSupported() is true and tray initialization succeeds:

  • Closing the dashboard hides the window.
  • The Agent keeps running.
  • Heartbeat continues running.
  • The tray menu can open the dashboard again.
  • The tray menu can pause or resume the worker through the same controller flow used by the dashboard.
  • Exit from the tray performs controlled shutdown.

When System Tray is unsupported or fails to initialize, the application keeps the standard JavaFX lifecycle and closing the window exits the application.

Tests And CI

Run the full local verification:

mvn clean verify

The current suite has 92 tests. This number can grow as the Agent evolves.

GitHub Actions workflow:

.github/workflows/agent-ci.yml

The CI matrix runs on:

  • Ubuntu
  • Windows
  • macOS

CI uses Temurin 21, Maven cache, and uploads Surefire reports only on failure.

Documentation

Project Status

The Agent foundation is implemented and is being prepared for future Task Protocol integration.