Hyve Documentation

Complete guide to setting up isolated workspaces for AI agents

npm install -g hyve-cli

Overview

Hyve creates isolated workspaces for AI coding agents. Each workspace gets its own git branch, database clone, and unique ports - so you can run multiple agents in parallel without conflicts.

Git Worktrees

Each workspace is a separate git worktree with its own branch. Changes stay isolated until you're ready to merge.

Database Cloning

Instant PostgreSQL snapshots using Docker. Each workspace gets a fresh copy of your database on a unique port.

Port Isolation

Services get unique ports per workspace. Run multiple dev servers simultaneously without conflicts.

Agent Ready

Works with Claude, Cursor, Aider, and any AI agent. Just point them at the workspace directory.

Installation

Install Hyve globally using npm:

npm install -g hyve-cli

Requirements

Node.js 18+
Git 2.30+
Docker (for database cloning)
pnpm (or npm/yarn)

Quick Start

1. Initialize Hyve in your project

cd your-monorepo
hyve init

This creates a .hyve.yaml configuration file with default settings.

2. Create a workspace

# Create workspace with specific repos
hyve create auth-feature server webapp

# Create from a specific branch
hyve create billing-api --from feature/stripe server

3. Start services

hyve run auth-feature

This starts all configured services on workspace-specific ports.

4. Point your AI agent at the workspace

# Claude Code
claude-code --cwd ~/workspaces/auth-feature

# Cursor
cursor ~/workspaces/auth-feature

# Aider
cd ~/workspaces/auth-feature && aider

Configuration

Hyve is configured via .hyve.yaml in your project root:

main_repo: .
repos:
  server:
    path: ./server
    setup: pnpm install
  webapp:
    path: ./webapp
    setup: pnpm install

required_repos:
  - server

database:
  source_container: postgres-main
  base_port: 5500

services:
  base_port: 4000
  port_offset: 1000
  definitions:
    server:
      default_port: 3000
      dev_command: pnpm dev
      env_var: PORT
    webapp:
      default_port: 3001
      dev_command: pnpm dev

Configuration Options

Option	Description	Default
`main_repo`	Path to the main repository	`.`
`repos`	Map of repository definitions	-
`required_repos`	Repos always included in workspaces	`[]`
`services.base_port`	Starting port for workspace 0	`4000`
`services.port_offset`	Port increment between workspaces	`1000`
`database.source_container`	Docker container to clone from	-

Commands

hyve init

Initialize Hyve in the current directory.

hyve init

hyve create

Create a new isolated workspace.

hyve create <name> [repos...] [options]

# Options:
  --from <branch>    Base branch for the worktree
  --no-db            Skip database cloning

hyve run

Start all services in a workspace.

hyve run <workspace>

hyve stop

Stop all services in a workspace.

hyve stop <workspace>

hyve list

List all workspaces and their status.

hyve list

hyve attach

Attach a new repo/service to an existing workspace.

hyve attach <workspace> [repos...]

# Options:
  --no-setup    Skip running setup scripts

# Examples:
hyve attach auth-feature webapp      # Add webapp to existing workspace
hyve attach billing-api              # Interactive repo selection

hyve cleanup

Remove a workspace and its resources.

hyve cleanup <workspace>

# Options:
  --keep-branch    Don't delete the git branch
  --keep-db        Don't remove the database container

Port Isolation

Each workspace gets unique ports calculated from the base configuration:

workspace_base = base_port + (workspace_index * port_offset)
service_port = workspace_base + (service_default_port - 3000)

Example: With base_port: 4000 and port_offset: 1000:

Workspace	Server (3000)	Webapp (3001)	API (3002)
workspace-0	`:4000`	`:4001`	`:4002`
workspace-1	`:5000`	`:5001`	`:5002`
workspace-2	`:6000`	`:6001`	`:6002`

Database Cloning

Hyve clones your PostgreSQL database using Docker:

# Your main database runs in a container
docker run -d --name postgres-main -p 5432:5432 postgres

# Hyve clones it for each workspace
hyve create my-feature server
# Creates container: postgres-hyve-my-feature on port 5500

Note: Database cloning requires your source database to be running in a Docker container. Hyve uses docker exec to create dumps and restore them to new containers.

Using with AI Agents

Claude Code

# Create workspace and start services
hyve create payment-flow server webapp
hyve run payment-flow

# Launch Claude in the workspace
cd ~/workspaces/payment-flow
claude

# Or specify the working directory
claude --cwd ~/workspaces/payment-flow

Cursor

# Open workspace in Cursor
cursor ~/workspaces/payment-flow

Aider

cd ~/workspaces/payment-flow
aider --model claude-3-opus

Running Multiple Agents in Parallel

# Terminal 1: Claude working on auth
hyve create auth-feature server
hyve run auth-feature
claude --cwd ~/workspaces/auth-feature

# Terminal 2: Cursor working on billing
hyve create billing-api server
hyve run billing-api
cursor ~/workspaces/billing-api

# Terminal 3: Aider working on UI
hyve create ui-refactor webapp
hyve run ui-refactor
cd ~/workspaces/ui-refactor && aider

Tip: Each workspace uses unique ports, so all three agents can run full dev environments simultaneously without conflicts.