OpenHuskyAgent

Step 1: Pick Your Install Path

Linux / VPS Quick Install

Use the installer when you want the fastest setup on a Linux host.

Safer install path:

curl -fsSLO https://raw.githubusercontent.com/HandleCoding/OpenHuskyAgent/main/install.sh
less install.sh
bash install.sh

Convenience shortcut for trusted environments:

curl -fsSL https://raw.githubusercontent.com/HandleCoding/OpenHuskyAgent/main/install.sh | bash

Useful options:

bash install.sh --non-interactive
bash install.sh --install-dir="$HOME/openHusky" --port=18088
bash install.sh --upgrade
husky update

The installer clones the repository into ~/openHusky by default, installs JDK 17+ when needed, builds the service and TUI client JARs, writes runtime config to ~/.husky/.env, creates the ~/.husky/config, ~/.husky/skills, ~/.husky/db, ~/.husky/logs, and ~/.husky/memory directories, generates a random HUSKY_API_KEYS value, and can install a systemd service.

bin/husky prefers ~/.husky/.env and only falls back to the repo-local .env when the user-level config file is missing.

macOS Quick Install (Homebrew)

For the smoothest macOS install path, use the official Homebrew tap.

brew tap HandleCoding/husky
brew install HandleCoding/husky/husky
husky init
husky serve

After husky init, edit ~/.husky/.env and set OPENAI_API_KEY at minimum. Then choose one startup mode:

• Foreground: husky serve
• Background: husky start

To upgrade a Homebrew install later:

brew update
brew upgrade HandleCoding/husky/husky

Homebrew installs openjdk@17 automatically, installs the husky launcher into your PATH, and keeps the runtime bundle under Homebrew-managed libexec.

macOS / Windows / Any Platform From Source

Use the source path when you are developing locally or not on Linux.

Requirements:

• JDK 17+
• Git
• An OpenAI-compatible chat model endpoint
• Optional: Brave or Tavily API key for web search
• Optional: Playwright Chromium for browser tools
• Optional: Docker for Docker execution backend experiments

git clone https://github.com/HandleCoding/OpenHuskyAgent.git
cd OpenHuskyAgent
mkdir -p ~/.husky
cp .env.example ~/.husky/.env

If you prefer a repo-local config for source-only work, bin/husky still falls back to .env when ~/.husky/.env does not exist.

Step 3: Build And Start Husky

./mvnw -B -ntp clean install
bin/husky serve

Success signal: the service keeps running in the current terminal and starts listening on port 18088 unless you changed HUSKY_PORT.

For local development, bin/husky dev starts the service and TUI together, but serve + tui is the clearest first-run path.

Upgrade An Existing Install

The recommended local upgrade path depends on how you installed Husky.

For a Homebrew install on macOS:

brew update
brew upgrade HandleCoding/husky/husky

For a git checkout managed with install.sh, use:

husky update

husky update wraps bash install.sh --upgrade, refuses to run on a dirty checkout, and prints the active code/config/memory paths after the upgrade.

If you want the lower-level command explicitly, this still works:

bash install.sh --upgrade

Build packages without tests

./mvnw -B -ntp -DskipTests package

Quick Start

The goal is to get Husky working once in under a minute: install, start the service, verify health, then open the TUI.

Step 2: Set Minimal Configuration

Edit ~/.husky/.env and set at least:

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com
OPENAI_MODEL=gpt-5.4

OPENAI_API_KEY is the only strictly required value for a first run if the default base URL and model work for your provider.

Minimal Configuration

Most deployments only need .env:

Browser and MCP integrations are disabled by default. Enable them only when configured intentionally.

Background Service Options

husky serve keeps the service in the current terminal. On macOS or other environments without systemd, use the lightweight background commands:

husky start
husky status
husky logs
husky stop

This mode writes its PID to ~/.husky/husky.pid and logs to ~/.husky/logs/husky-serve.log.

For long-running Linux server deployments, systemd is still the recommended path:

sudo systemctl start husky-agent
sudo systemctl status husky-agent
journalctl -u husky-agent -f

Configuration Reference

Most runtime defaults live in service/src/main/resources/application.yml.

Storage defaults to local. Non-local workspace/checkpoint providers are extension points; unsupported remote types fail fast instead of silently falling back to local behavior.

Chatbot SSE API

curl -N \
  -H 'X-Api-Key: <your-api-key>' \
  -H 'X-User-Id: demo-user' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"message":"Search the latest Spring AI docs"}' \
  http://localhost:18088/api/chat

Request fields:

Headers:

SSE events include token, reasoning, message, tool_started, tool_completed, tool_failed, done, and error.

Default tests; excludes live API and browser groups

./mvnw -B -ntp test

Explicit live API compatibility tests

OPENAI_API_KEY=... ./mvnw -B -ntp test -P live-api-tests

Module tests

./mvnw -B -ntp test -pl infra ./mvnw -B -ntp test -pl domain ./mvnw -B -ntp test -pl application ./mvnw -B -ntp test -pl service ./mvnw -B -ntp test -pl client