HarborForge

Agent / human collaborative task-management platform — manages the full proposal → milestone → task lifecycle with strict state machines, plus a CLI, monitoring, and OpenClaw integration.

Repository layout

This is the umbrella repository; every component is a git submodule:

HarborForge/
├── AbstractWizard/             # Go, secure first-time setup service (SSH tunnel, port 8080)
├── HarborForge.Backend/        # Python/FastAPI, core REST API + RBAC (port 8000)
├── HarborForge.Frontend/       # React + TypeScript + Vite single-page app (port 3000)
├── HarborForge.Cli/            # Go command-line client `hf`
├── HarborForge.Monitor/        # Go host telemetry client (optional local bridge 9100)
├── HarborForge.OpenclawPlugin/ # Node OpenClaw plugin `harbor-forge`
├── HarborForge.Test/           # Integration tests (backend pytest / frontend Playwright)
├── docker-compose.yml          # Docker orchestration
├── nginx-host.conf.example     # Host nginx config example
└── .env.example                # Environment variable template

Quick start

# Clone and initialize all submodules
git clone --recurse-submodules https://git.hangman-lab.top/zhi/HarborForge.git
cd HarborForge
# If already cloned without submodules:
git submodule update --init --recursive

# Configure environment (do NOT use the defaults — see "Security")
cp .env.example .env
# Edit .env: set at minimum a strong random SECRET_KEY and DB passwords

# Start the services
docker compose up -d

First deployment — setup wizard

HarborForge uses AbstractWizard for secure initialization. The wizard listens on 127.0.0.1 only and must be reached over an SSH tunnel.

# 1. SSH tunnel: forward the wizard port to your machine
ssh -L 18080:127.0.0.1:18080 user@your-server

# 2. Open the frontend in a browser (or via the host nginx).
#    If the backend is not initialized, it redirects to the setup wizard.

# 3. In the wizard, configure: database connection, admin account,
#    default project (optional).

# 4. Once saved, the backend detects the config and starts; refresh
#    the page → login screen.

Startup flow

docker compose up
  ├── mysql    → database starts
  ├── wizard   → AbstractWizard starts (127.0.0.1, SSH-tunnel access)
  ├── backend  → blocks waiting for the config file (polls /config/harborforge.json)
  └── frontend → checks backend state
                 ├── backend not ready → shows the setup wizard (SSH tunnel to wizard)
                 └── backend ready     → normal login screen

Security model

• The wizard port binds to 127.0.0.1 and is never exposed to the external network; initialization must be done over an SSH tunnel.
• Config is shared with the backend via a Docker volume (never over the network); the backend mounts it read-only.

Deployment architecture

Host nginx (80/443)
  ├── /     → frontend (Docker, port 3000)
  └── /api/ → backend  (Docker, port 8000)

Internal to Docker (not exposed):
  wizard (127.0.0.1) → config management, SSH-tunnel access
  wizard_config vol  → written by wizard, read-only for the backend
  mysql (127.0.0.1)  → data persistence

Submodules

Submodule	Stack	Role
AbstractWizard	Go	First-time setup wizard; atomic config writes + backups; init/readonly modes
HarborForge.Backend	Python / FastAPI / SQLAlchemy / MySQL	Core API: users, projects, tasks, milestones, proposals, RBAC, webhooks, worklogs, notifications
HarborForge.Frontend	React 18 / TS / Vite	SPA, ~20 pages; auto-detects an uninitialized backend → setup wizard
HarborForge.Cli	Go	Permission-aware command-line client hf
HarborForge.Monitor	Go	Standalone host telemetry client, heartbeat reporting
HarborForge.OpenclawPlugin	Node / TS	OpenClaw plugin; bridges telemetry; can install the hf skills and calendar scheduling
HarborForge.Test	pytest / Playwright	Backend and frontend integration tests

Core domain model

• Milestone: open → freeze → undergoing → completed (freeze requires exactly one release task)
• Task (issue / story / test / maintenance / research / review / resolution): pending → open → undergoing → completed; completion requires a comment
• Proposal: a user proposes → a manager accepts → a feature-story task is auto-created in a milestone; rejected proposals can reopen
• RBAC: fine-grained permissions + a project role hierarchy (guest < viewer < member < dev < mgr < admin)

Ports

Service	Container port	Bind	Env var
Frontend	3000	see compose	FRONTEND_PORT
Backend	8000	see compose	BACKEND_PORT
MySQL	3306	127.0.0.1	MYSQL_PORT
Wizard	8080	127.0.0.1	WIZARD_PORT

The SSH-tunnel example uses local port 18080 forwarding to the server-side wizard.

Security

Before deploying, you must:

• Set a strong random SECRET_KEY (e.g. openssl rand -hex 32). The backend refuses to start on a weak/default/short key.
• Not use the placeholder passwords from .env.example; set a strong MySQL password.
• Never commit a .env containing real secrets.

The backend's auth / RBAC / SSRF hardening is documented in the "Security" section of the HarborForge.Backend README.

Frontend

The frontend uses a centralized custom design system (the industrial "Foundry Deck" theme); see the HarborForge.Frontend README for details.