dust-hive

What is dust-hive?

dust-hive is a CLI tool for running multiple isolated Dust development environments simultaneously. Each environment gets its own:

• Git worktree (separate branch)
• Port range (no conflicts between environments)
• Docker containers (isolated volumes)
• Database instances (Postgres, Qdrant, Elasticsearch)

Detecting a dust-hive Environment

To check if you're currently running in a dust-hive environment:

1. Check working directory: dust-hive worktrees are located at

   ~/dust-hive/{env-name}/

2. Check for worktree: The

   .git

   file (not directory) indicates a git worktree

# Check if in worktree path
pwd | grep -q "$HOME/dust-hive/" && echo "In dust-hive environment"

Environment States

Environments can be in one of three states:

State	What's Running	Can Run Tests?
stopped	Nothing	No
cold	SDK watch only	Yes (front tests use shared test DB)
warm	All services (front, core, connectors, oauth, workers) + Docker	Yes

Check the current state:

dust-hive status [ENV_NAME]

Environment Variables (direnv)

Each dust-hive worktree contains a

.envrc

file that automatically loads environment variables when you

cd

into the directory. This is powered by direnv.

What this means:

• Environment variables (ports, database URIs, API keys, etc.) are automatically available
• Variables like

  FRONT_DATABASE_URI

  ,

  CORE_API

  ,

  CONNECTORS_API

  are pre-configured for the environment's port range

If environment variables are missing, manually source the environment:

source ~/.dust-hive/envs/{ENV_NAME}/env.sh

Port Allocation

Each environment gets a 1000-port range starting at 10000:

• 1st env: 10000-10999 (front:10000, core:10001, connectors:10002, oauth:10006)
• 2nd env: 11000-11999
• 3rd env: 12000-12999

Running Linters, Type Checks, and Builds

For dust-hive itself (in

x/henry/dust-hive/

):

# Run ALL checks before committing (MANDATORY)
bun run check

# Individual checks
bun run typecheck    # TypeScript strict checks
bun run lint         # Biome linting
bun run lint:fix     # Auto-fix lint issues
bun run format       # Code formatting
bun run test         # All tests

For Dust apps (in worktree or main repo):

# TypeScript SDK (watch is running - check logs if issues after SDK changes)
dust-hive logs [ENV_NAME] sdk

# Front (Next.js)
cd front && npm run lint                                              # ESLint
cd front && NODE_OPTIONS="--max-old-space-size=8192" npx tsgo --noEmit  # Type-check
cd front && npm run build                                             # Build

# Core (Rust)
cd core && cargo check && cargo clippy

# Connectors
cd connectors && npm run lint   # ESLint
cd connectors && npm run build  # Type-check + build

# OAuth (Rust)
cd oauth && cargo check && cargo clippy

Quick health check after warming:

curl -sf http://localhost:10000/api/healthz  # front
curl -sf http://localhost:10001/             # core

Running Front Tests in Cold Environments

The

front

project requires a Postgres database and Redis to run tests. dust-hive provides shared test containers that allow running front tests without warming up the full environment.

How it works

• A shared Postgres container runs on port 5433 (started by

  dust-hive up

  )
• A shared Redis container runs on port 6479 (started by

  dust-hive up

  )
• Each environment gets its own test database:

  dust_front_test_{env_name}

• TEST_FRONT_DATABASE_URI

  and

  TEST_REDIS_URI

  are already set in each environment's

  env.sh

Running front tests

IMPORTANT: You must set

NODE_ENV=test

when running front tests.

# From any cold environment, run front tests directly
cd front && NODE_ENV=test npm test

# Run specific test file
cd front && NODE_ENV=test npm test lib/resources/user_resource.test.ts

# Run with verbose output
cd front && NODE_ENV=test npm test --reporter verbose path/to/test.test.ts

No need to warm the environment - the shared test Postgres and Redis are always available.

Troubleshooting front tests

If front tests fail with database connection errors:

1. Check if test postgres is running:

   docker ps | grep dust-hive-test-postgres

2. If not running, start it:

   docker start dust-hive-test-postgres

3. Verify the database exists:

   docker exec dust-hive-test-postgres psql -U test -l

Known Issues

Node modules structure

In dust-hive environments,

node_modules

for

front

and

connectors

uses a shallow copy structure:

• A real

  node_modules

  directory with symlinks to packages from the main repo

• @dust-tt/client

  is overridden to point to the worktree's SDK (ensuring correct type resolution)

Running

npm install

requires manual cleanup:

rm -rf node_modules && npm install

SDK watcher doesn't detect changes after git rebase

The SDK watcher uses nodemon which relies on filesystem events. When running

git rebase

,

git pull

, or

git checkout

, nodemon may not detect file changes.

Symptoms: Type errors in front about missing types that should exist in the SDK.

Solution: Restart the SDK watcher after git operations that change SDK files:

dust-hive restart [ENV_NAME] sdk

Or manually trigger a rebuild:

touch sdks/js/src/types.ts