feat: unify setup-dev flow into shared setup module

[nick-inkeep]

Summary

Extracts the setup-dev flow into a shared @inkeep/agents-core/setup module. The monorepo's bash setup.sh (223 lines) and the template's setup.js (623 lines) are replaced by thin wrappers (~30-60 lines) that pass config to a single runSetup() entry point.

Key decisions

Why a shared module in agents-core (not a standalone package or script)

The setup flow needs access to loadEnvironmentFiles() from agents-core and must be importable by both the monorepo (scripts/setup-dev.js) and the published quickstart template (create-agents-template). Putting it in agents-core/setup avoids a new package while keeping it co-located with the env/auth/db primitives it depends on. Trade-off: agents-core grows slightly, and the monorepo wrapper must build agents-core before running setup (visible in the Cypress CI change).

Config-driven callers instead of flags

Each caller passes a SetupConfig object (compose file path, migration commands, push target, server commands, isCloud, skipPush). This avoids a flag explosion on a single CLI and lets each context (monorepo contributor vs. quickstart user vs. cloud deploy) declare exactly what it needs. The shared module has zero awareness of who's calling it.

Pre-flight checks before Docker startup

Rather than letting docker-compose up fail cryptically on port conflicts, the module runs lsof + docker ps + docker inspect to identify which Docker Compose project owns the conflicting port and tells the user the exact docker compose -p <name> down command. For standalone (non-compose) containers, it suggests docker rm -f <name>. If the ports belong to our own project, startup is skipped (idempotent re-run).

When Docker is unavailable, the module checks whether database URLs point to localhost or an external host. Localhost URLs (from .env.example defaults) indicate Docker-managed DBs are expected, so setup exits with an error. External host URLs indicate the user is managing DBs externally, so Docker is skipped gracefully.

Health polling: all three database services

After docker-compose up -d, health polling checks all three services in parallel: doltgres-db (60s timeout), postgres-db (30s), and spicedb-postgres (30s). Setup only hard-fails if both primary databases (doltgres + postgres) fail health checks — a SpiceDB-only failure logs a warning but continues, since writeSpiceDbSchema() in auth init has its own 30-retry logic.

Auth strategy: bypass secret vs. CLI keychain

When INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET is available, push uses CI mode (INKEEP_CI=true + INKEEP_API_KEY). When it's absent (cloud users), the CLI resolves auth from keychain/profile — the template pre-runs inkeep init --no-interactive + inkeep login before calling runSetup(). This means local contributors and cloud users follow different auth paths through the same code, controlled entirely by the presence of the bypass secret.

Process group cleanup for temporarily spawned servers

When the API server is spawned for project push, it's started with detached: true so it gets its own process group. Cleanup uses kill(-pid) (negative PID = group signal) followed by a 2-second grace period and SIGKILL. This prevents orphaned Node processes after setup completes.

CI concurrency limit

Added --concurrency=8 to pnpm check in CI. On cache-miss runs, unlimited Turbo concurrency causes multiple Next.js builds to run simultaneously on a 4-vCPU runner, triggering OOM kills. This is tangential to the setup unification but was discovered and fixed during CI validation of this PR.

User scenarios addressed

Scenario	Behavior
First-time contributor runs pnpm setup-dev	Full flow: .env creation, JWT gen, Docker startup, migrations, auth init, project push
Re-run after setup already completed	Idempotent: skips JWT gen (keys exist), skips Docker startup (containers running), migrations apply only what's new
Another Docker project occupies port 5432/5433/5434	Pre-flight detects conflict, reports project name and exact docker compose -p <name> down command (or docker rm -f <name> for standalone containers), continues with existing DBs
Docker not installed, DB URLs point to external host	Graceful degradation: skips Docker entirely, runs migrations against external DBs
Docker not installed, DB URLs are localhost	Exits with error — localhost URLs indicate Docker-managed DBs are expected
pnpm setup-dev --skip-push	Runs env/Docker/migrations/auth but skips server spawn and project push
docker compose up slow on cold start	Timeout (120s) triggers warning, falls through to health polling which waits for containers to become healthy
Quickstart template setup (local)	Same flow via @inkeep/agents-core/setup, different compose file and migration commands
Quickstart template setup (cloud, no bypass secret)	Runs inkeep init + inkeep login before setup, push authenticates via CLI keychain
Cypress E2E in CI	Builds agents-core first, runs setup-dev --skip-push (no project push needed for E2E)

Changes

• packages/agents-core/src/setup/setup.ts — Shared setup module (~730 lines). Includes isLocalDatabaseUrl() helper for localhost detection and health polling for all 3 DB services.
• scripts/setup-dev.js — Monorepo wrapper (32 lines), replaces deleted scripts/setup.sh
• create-agents-template/scripts/setup.js — Rewritten as thin wrapper
• .github/workflows/ci.yml — --concurrency=8 on pnpm check
• .github/composite-actions/cypress-e2e/action.yml — Build agents-core before setup; --skip-push
• agents-cookbook/template-projects/inkeep.config.ts — Added apiKey from bypass secret env var
• agents-docs/ — Updated contributing overview + added troubleshooting section for local env issues
• .gitignore — Added .setup-complete marker file

Test coverage

Unit tests (17 cases in setup.test.ts)

Covers the core runSetup() logic with mocked exec/spawn/fetch:

• Migration execution (manage + runtime, parallel)
• Auth init (with credentials, without credentials)
• Docker skip when isCloud: true
• Docker startup when ports are free
• SpiceDB PostgreSQL health-checked alongside doltgres and postgres
• Docker skip when pre-flight detects foreign containers on required ports
• Docker compose timeout during startup (graceful continue to health polling)
• Docker unavailable with external DB URLs (graceful skip)
• Docker unavailable with localhost DB URLs (exits with error)
• Missing DB URLs on non-cloud (exits with error)
• Project push command format and env var pass-through
• Push with bypass secret (CI mode: INKEEP_CI, INKEEP_API_KEY, INKEEP_TENANT_ID)
• Push without bypass secret (CLI keychain auth, no CI env vars)
• --skip-push flag honored
• Server already running (no spawn)
• Server not running (spawn + wait for health)

Test plan

Manual QA scenarios tested on macOS (2026-02-18). These resist automation because they require real Docker, real database startups, and real process lifecycle behavior.

• Clean-state full flow: pnpm setup-dev from scratch (after docker-compose down -v + removing .setup-complete). All 8 steps completed: .env check, JWT skip (already configured), Docker startup with health polling, manage + runtime migrations, auth init, API server temporary spawn, weather-project push, server cleanup. · Why not a test: requires real Docker daemon, real database containers, real network health checks.
• Idempotency re-run: pnpm setup-dev immediately after successful first run. JWT gen skipped ("already configured"), Docker up -d is a no-op (containers already healthy), all three health checks pass (DoltgreSQL, PostgreSQL, SpiceDB PostgreSQL), migrations ran cleanly, project re-pushed successfully. · Why not a test: requires persistent state across runs (.setup-complete file, running containers).
• --skip-push flag: pnpm setup-dev --skip-push completes after Step 5 (auth init). No Step 6/7/8 output, no API server spawned, ends with "Database setup completed!" message. · Why not a test: verifiable via unit test (already covered), but manual run confirms real end-to-end flag plumbing.
• Port conflict detection: Stopped our containers, started a foreign postgres on port 5432 (docker run -d --name conflict-test -p 5432:5432 postgres:16). Setup correctly detected :5432 (DoltgreSQL) → conflict-test, printed the conflict warning, skipped Docker startup, and proceeded to migrations. · Why not a test: requires real Docker containers, real port binding, real lsof + docker inspect calls.
• Localhost detection regex: Validated isLocalDatabaseUrl() against 10 edge cases including false-positive guards (localhost in DB name, localhost in password). · Why not a test: could be a unit test; validated via inline Node script during QA.
• CI pipeline: build, typecheck, lint, unit tests all green.
• Create Agents E2E: Template setup flow green.
• Cypress E2E: Docker-missing graceful degradation path green.

Bugs found and fixed during QA

1. Exec timeout misclassified as port conflict (fixed in cee4e1eb2): startDockerDatabases() treated killed === true (Node exec timeout) as a port conflict, skipping health polling. On cold starts where Docker needed to pull images, this caused migrations to fail against containers that weren't ready. Fix: separated timeout from port-conflict handling — timeouts now fall through to health polling, and the exec timeout was increased from 60s to 120s.

2. No fix suggestion for non-compose containers (fixed in cee4e1eb2): Port conflict detection showed an empty "Fix:" section for standalone containers without a com.docker.compose.project label. Fix: added docker rm -f <name> fallback for non-compose containers.

Review feedback addressed

3. DB URL existence check was meaningless (fixed in 22d5934): .env.example always provides localhost DB URLs, so the "Docker not available but DB URLs are set" fallback always passed. Fix: replaced existence check with isLocalDatabaseUrl() — localhost URLs require Docker; external host URLs allow graceful Docker skip.

4. SpiceDB PostgreSQL not health-checked (fixed in 22d5934): Health polling only checked doltgres-db and postgres-db, missing spicedb-postgres (port 5434). Fix: added spicedb-postgres to the Promise.allSettled health polling with 30s timeout.

Future considerations

• waitForServerReady exists in 4 variants across the repo (setup.ts, create-agents/e2e/utils.ts, agents-cli/dev.ts, agents-sdk/module-hosted-tool-manager.ts). Consolidation was considered but deferred — the implementations differ intentionally (exponential backoff vs. fixed interval, CI-aware logging vs. silent, HTML body check vs. status code, etc.). A unified function flexible enough for all cases would be more complex than the ~15-line inline versions. Revisit if more call sites emerge.

---

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 073a471

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@inkeep/agents-core	Patch
@inkeep/agents-api	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-cli	Patch
@inkeep/agents-sdk	Patch
@inkeep/agents-work-apps	Patch
@inkeep/ai-sdk-provider	Patch
@inkeep/create-agents	Patch
@inkeep/agents-mcp	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Feb 19, 2026 3:40am
agents-docs	Ready	Preview, Comment	Feb 19, 2026 3:40am
agents-manage-ui	Ready	Preview, Comment	Feb 19, 2026 3:40am

[claude]

PR Review Summary

(0) Total Issues | Risk: Low

Re-review Summary

This is a re-review triggered by pull_request:synchronize. The head SHA (073a4716b) matches the previously approved state. No new PR-specific code changes since the last approval.

This PR has been thoroughly reviewed across 15+ prior review cycles, all resulting in approval. The comprehensive review history includes:

Review Cycle	Focus	Outcome
Initial review	Full PR analysis	4 findings raised (3 Major, 1 Minor, 1 Consider)
Author responses	Feedback triage	1 accepted (JWT error context), 4 declined with valid rationale
Fix verification	JWT error logging	Fix correctly implemented
Delta reviews (12×)	Pre-flight checks, compose detection, cloud mode push, localhost detection, SpiceDB health polling, CI service containers	All approved

Prior Feedback Status

All 5 prior automated inline threads are resolved:

Finding	Resolution
🟠 Windows compatibility	Declined ✓ — module is Unix-only throughout (sh, docker-compose, SIGTERM/SIGKILL)
🟠 JWT error context	Fixed ✓ — logError() now surfaces diagnostic details
🟠 Server spawn failure detection	Declined ✓ — out of scope, health-check timeout surfaces failures
🟡 copyFileSync errors	Declined ✓ — unhandled exception appropriate for setup-critical path
💭 .mjs extension	Declined ✓ — "type": "module" makes this cosmetic churn

Human Review Status

Human reviewer @miles-kt-inkeep approved on 2026-02-18T22:49:50Z with 3 comments:

• ✅ Localhost URL detection — Fixed (added isLocalDatabaseUrl() helper)
• ✅ SpiceDB health check — Fixed (added to parallel health polling)
• 🟡 waitForServerReady duplication — Acknowledged as valid future cleanup (low priority)

🕐 Pending Recommendations (1)

• 🟡 setup.ts:485 waitForServerReady duplicates functionality in e2e utils — valid observation for future consolidation, low priority

---

✅ APPROVE

Summary: This PR successfully unifies ~600 lines of duplicated setup logic into a shared @inkeep/agents-core/setup module. The architecture is clean, error handling is appropriate for CLI context, tests cover core scenarios (17 test cases), CI integration is correct, and documentation accurately reflects the new behavior. Human reviewer has approved. All substantive feedback has been addressed. Ship it! 🚀

Reviewers (0)

No reviewers dispatched — this sync event contains no new PR-specific code changes since the last approved review.

[github-actions]

🔎💬 Inkeep AI search and chat service is syncing content for source 'Inkeep Agent Framework Docs'