Codespaces onboarding friction: missing docs generation + unclear multi-service startup

[Saptami191]

I was onboarding Hatchet in GitHub Codespaces and ran into a few developer experience/setup issues that made the local startup flow difficult to understand.

Environment:

• GitHub Codespaces
• frontend/app via pnpm dev
• Docker infra started successfully
• Go services started manually

Issues encountered:

1. Missing generated docs dependency
   Frontend initially failed with:
   Failed to resolve import "@/lib/generated/docs"

This required manually discovering and running:
pnpm docs:gen

It was not obvious during frontend setup.

2. Multi-service startup flow unclear
   The frontend depends on:

• API service on :8080
• control-plane/engine service on :8081

Initially only the API was started, which caused repeated:
ECONNREFUSED 127.0.0.1:8081

It wasn’t immediately clear which binaries/services needed to run together for local development.

3. Codespaces / forwarded-port auth friction
   Cookie domain configuration caused auth/session issues in Codespaces forwarded URLs. The default local cookie-domain assumptions seem optimized for local machine domains rather than cloud dev environments.

Suggestions:

• add a dedicated Codespaces onboarding section
• document required startup order for local development
• explicitly mention pnpm docs:gen
• provide a single local-dev startup command/script if possible
• clarify which services map to ports 8080 and 8081

Core infrastructure itself worked correctly:

• Postgres
• RabbitMQ
• migrations
• API
• engine

This issue is mainly about onboarding clarity and local DX.

[Saptami191]

@gregfurman Hi! I spent some time onboarding the repo in GitHub Codespaces and wanted to share a few setup friction points I ran into in case it helps improve local DX/documentation.

Main things that slowed onboarding:

• frontend initially failed because pnpm docs:gen was required before pnpm dev
• it wasn’t immediately obvious that both hatchet-api (:8080) and hatchet-engine (:8081) need to run for frontend functionality
• auth/cookie setup was tricky in Codespaces forwarded-port environments because of cookie-domain assumptions

The core infra itself worked correctly once everything was running:

• Postgres
• RabbitMQ
• migrations
• API
• engine

This feels more like onboarding/documentation friction than a core bug, but I figured the feedback might still be useful for new contributors trying local setup in Codespaces/cloud dev environments.

I’m still exploring the codebase and interested in contributing further, so I wanted to document the setup path while it was still fresh.