Skip to content

getting-started.md

Latest commit

 

History

History
435 lines (312 loc) · 12.1 KB

getting-started.md

File metadata and controls

435 lines (312 loc) · 12.1 KB

Getting Started with OpenHive

This guide follows the supported preview path:

  • PostgreSQL via docker compose
  • backend from source with uv
  • dashboard from source with npm
  • optional Feishu setup after the core dashboard flow works

This path is the current OpenHive install mode preview_local. It is intentionally different from a future packaged docker_quickstart. See docs/installation-modes.md for the install-mode matrix and ownership boundaries. See docs/env-ownership.md for the managed .env subset that future installer flows may own while preserving unrelated operator keys.

The governed workspace-task sandbox already exists as a real runtime surface, but in preview_local it remains an optional operator workflow rather than a required onboarding step. You can run the backend and dashboard without it; start it separately only if you want Keeper-driven dev-task flows on http://127.0.0.1:8091.

Prerequisites

Tool Version Purpose
Python 3.12+ Backend runtime
Node.js 20.9+ Dashboard
Docker 20+ PostgreSQL
uv latest Python package manager (pip install uv)
Feishu App — Optional bot messaging and channel routing

Install-mode note

For the current preview:

  • OpenHive manages the documented repo-local config surfaces and the local PostgreSQL compose service definition
  • you still run the backend and dashboard from source
  • external PostgreSQL modes are not part of the supported public preview path
  • contributor-only source_dev variations are outside this guide

If you need a different ownership model, treat this guide as the preview baseline and not as a general installer reference.

1. Recommended preview-local installer path

git clone https://github.com/terrywangcode/openhive.git
cd openhive
cd server
uv sync --all-extras
uv run openhive setup

openhive setup is now the default preview-local onboarding command. It:

  • creates the managed .env
  • writes .openhive/install-state.json
  • starts local Docker PostgreSQL
  • runs database migrations
  • prints the next backend and dashboard commands

The supported preview_local contract currently uses the fixed local ports 5432 for PostgreSQL, 8080 for the API, and 3000 for the dashboard dev server. The installer does not expose custom port flags for this flow yet.

Language resolution for the installer CLI is:

  1. --lang
  2. persisted install preference in .openhive/install-state.json
  3. OPENHIVE_LANG
  4. system locale inference
  5. English fallback

After setup:

cd ..
make run
cd web
npm install
npm run dev

Support commands:

cd server
uv run openhive status
uv run openhive doctor

Lifecycle follow-up commands for an existing preview_local install:

cd server
uv run openhive update --yes
uv run openhive uninstall --yes
uv run openhive purge --confirm "PURGE OPENHIVE"
  • openhive update refreshes installer metadata and runs pending migrations without silently rewriting unrelated operator-owned config
  • openhive uninstall stops managed preview-local services and marks the install inactive while preserving project data and installer backups
  • openhive purge is the destructive path; it removes only managed local preview-local resources after typed confirmation and never drops an external PostgreSQL instance automatically
  • deferred install modes are still unsupported for these commands and fail closed rather than guessing at destructive semantics

1A. Manual contributor setup path

If you need the older source-first workflow for debugging or contributor work:

git clone https://github.com/terrywangcode/openhive.git
cd openhive
cp .env.example .env

For the current preview, manual .env editing remains available as a fallback. That fallback does not change the installer ownership boundary.

Edit .env with at least:

# Database
DATABASE_URL=postgresql+asyncpg://hive:password@localhost:5432/hive
DB_PASSWORD=password

# At least one LLM provider
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...

# Dashboard auth
DASHBOARD_SESSION_SECRET=change-me-in-production
HIVE_ADMIN_USERNAME=admin
HIVE_ADMIN_PASSWORD=change-me

# Local source-based runtime workspace
HIVE_WORKSPACE=.runtime

# Optional sandbox for Keeper dev tasks
HIVE_SANDBOX_URL=http://127.0.0.1:8091
HIVE_INTERNAL_SECRET=dev-task-internal-secret
# HIVE_SANDBOX_CODING_BACKEND=codex_cli
# HIVE_SANDBOX_ALLOWLIST_DOMAINS=registry.npmjs.org,pypi.org

# Optional Feishu integration
# FEISHU_APP_ID=cli_xxxxxxxx
# FEISHU_APP_SECRET=your_secret
# FEISHU_VERIFICATION_TOKEN=your_verification_token
# FEISHU_ENCRYPT_KEY=your_encrypt_key

Why HIVE_WORKSPACE=.runtime? In the source-based setup, OpenHive keeps mutable runtime state under repo-local .runtime/projects, .runtime/extensions, and .runtime/db, while versioned defaults stay in the source tree. The containerized gateway overrides this to /data/hive.

2. Start PostgreSQL

docker compose up -d postgres

The bundled image is pgvector/pgvector:pg16, so the local database includes the vector extension used by OpenHive.

3. Install backend dependencies and migrate

cd server
uv sync --all-extras
uv run alembic upgrade head

If you are using the repo venv directly, run tests with server/.venv/bin/python as described in LESSONS.md.

4. Run the backend

From the repo root:

make run

Or directly:

cd server
uv run uvicorn hive.main:app --reload --port 8080

Verify the backend:

curl http://localhost:8080/healthz

Expected response:

{"status":"ok"}

Optional: run the sandbox

If you want Keeper-driven dev-task workflows locally, start the sandbox API in a second terminal. For the fastest source-local loop:

make run-sandbox

Or directly from the backend directory:

cd server
uv run uvicorn hive.container.sandbox_entrypoint:app --reload --port 8091

For a containerized local run that matches the sandbox image more closely:

make run-sandbox-container

Verify the sandbox:

curl http://localhost:8091/healthz

Expected response:

{"status":"ok","role":"sandbox"}

Notes:

  • This sandbox lane is optional in preview_local; it is not required for the baseline backend + dashboard setup.
  • If you do not need Keeper dev-task workflows, you can skip this step.
  • HIVE_SANDBOX_URL should point at the sandbox API address shown above.
  • make run-sandbox is best for source-local dogfooding because the sandbox can directly see local paths and the checkout.
  • make run-sandbox-container is better for container image parity. When the container cannot see an operator host path, dev tasks must use workspace archive seeding or a configured apply relay to apply changes back safely.
  • source-local sandbox startup stores task and command runtime state under .runtime/sandbox/ when container-only /sandbox storage is not writable.
  • the canonical current coding path is the default HIVE_SANDBOX_CODING_BACKEND=codex_cli mode
  • HIVE_SANDBOX_CODING_BACKEND=relay_helper is an explicit opt-in proof mode for relay-backed sandbox validation, not the default local path
  • The runtime docs under docs/container-runtime-contracts.md and docs/deploy-k8s.md describe the same sandbox surface in container/Kubernetes terms; they do not make it a preview-default local step.

5. Run the dashboard

cd web
npm install
npm run dev

Open http://localhost:3000.

Notes:

  • the dashboard proxies /api/* to http://localhost:8080
  • the production build does not require fetching remote fonts
  • login is cookie-based; no localStorage token setup is needed

6. Log in with the bootstrapped admin account

On first boot, OpenHive creates the initial admin user automatically when both of these are set in .env:

  • HIVE_ADMIN_USERNAME
  • HIVE_ADMIN_PASSWORD

Use those credentials on the login page.

After login:

  1. Open Admin
  2. Create PM user accounts as needed
  3. Optionally generate invite codes for Feishu-side onboarding

No manual session-token generation is required for the supported preview flow.

7. Create your first project

Use the Dashboard first; it is the fastest way to verify the platform is working end to end.

  1. Open Projects
  2. Click New Project
  3. Choose a template
  4. Enter the project name and keywords
  5. Create the project and confirm you are redirected into the new project's setup flow

Then open the project detail page and verify that:

  • the project summary loads
  • the recommended setup order is visible
  • the Keeper pairing section is visible
  • Sessions and Runs pages render
  • Settings page is accessible

8. Optional: connect Feishu

If you want live message routing after the dashboard flow is working:

  1. Set the Feishu credentials in .env
  2. Restart the backend
  3. Open the project Settings page
  4. Add at least one Feishu channel
  5. Designate one channel as the Keeper channel
  6. Return to the project page and generate a Keeper pairing command
  7. Send the full pair ... command to the project-specific Keeper bot in Feishu
  8. Add Scouts if you need group coverage

Notes:

  • GatewayBot is for invite admission, activation reminders, and lightweight navigation
  • project creation, settings, and Keeper pairing are Dashboard-led flows
  • Scouts are optional; Keeper pairing is the critical first project handoff

For webhook-based local development, expose the backend with a tunnel such as ngrok:

ngrok http 8080

In Feishu Open Platform, configure:

  • Event Subscription URL: https://your-domain.com/webhook/feishu
  • Card Callback URL: https://your-domain.com/webhook/feishu/card
  • enable im.message.receive_v1

9. Run tests

Backend unit tests:

cd server
uv run pytest tests/ -v --tb=short -m "not integration"

API smoke tests:

cd server
uv run pytest tests/test_e2e/ -v --tb=short -m integration

Frontend tests:

cd web
npm test
npm run build

10. Backup and recovery

The repository includes a backup service in docker-compose.yml that runs scripts/backup.sh daily at 02:15.

It backs up:

  • PostgreSQL database dumps
  • .runtime/projects/ contents such as MEMORY.md, config.yaml, and runtime registries

The most important runtime project files are:

File Role
IDENTITY.md Durable identity and standing instructions for the project agent
MEMORY.md Durable project facts, decisions, and working knowledge
HEARTBEAT.md Keeper's editable scheduled checklist
SCOUTS_REGISTRY.md Runtime-managed Scout registry
memory/YYYY-MM-DD.md Recent durable log entries written by the runtime

Not all continuity state lives in these files. OpenHive also keeps runtime-managed session continuity such as persisted session summaries, session scratch memory, and checkpoints. Those are not general-purpose project docs and should not be treated as replacements for MEMORY.md.

To run a one-off backup manually:

DB_PASSWORD=<your_password> ./scripts/backup.sh /path/to/backup/dir

See docs/operations.md for restore steps and health-check commands.

Troubleshooting

Symptom Fix
ModuleNotFoundError: No module named 'packages' Run backend commands from server/; repo root is added in startup/test wiring
Dashboard login fails for the bootstrap admin Confirm both HIVE_ADMIN_USERNAME and HIVE_ADMIN_PASSWORD are set before first backend startup
401 Not authenticated on the dashboard Clear stale cookies, then log in again
next/font or Google Fonts build failures The current dashboard build is offline-safe; ensure you are on the updated code and rerun npm run build
asyncpg.exceptions.ConnectionDoesNotExistError PostgreSQL is not running — use docker compose up -d postgres
Keeper dev tasks cannot reach the sandbox Confirm make run-sandbox or make run-sandbox-container is running on port 8091 and HIVE_SANDBOX_URL=http://127.0.0.1:8091 in .env