local-dev-serve-troubleshooting

Common local dev setups

UI fast loop (Vite dev server)

• Start UI:

  • npm run dev

• In another terminal, start the Rust server:

  • cargo run -- serve --port 8080

Notes:

• lotar serve port flags: -p <PORT> and --port <PORT> both set the port. serve is the deliberate exception where -p means the port.
  • Correct: lotar serve -p 9000 or lotar serve --port 9000
  • Also accepted: lotar serve 9000 (positional port; kept for backward compatibility)
  • serve --project X is accepted and ignored; -p before the subcommand (e.g. lotar -p web serve) still selects the global project.
  • Running serve with no port configured anywhere prefers 8080 and moves to an OS-assigned port (with a warning) when it is busy; explicitly configured ports never move.
  • See: docs/help/serve.md

Production-like UI (embedded/static bundle)

• Build web assets:
  • npm run build:web
• Build the binary:
  • cargo build --release
• Run:
  • ./target/release/lotar serve --port 8080

Debugging tips

• If the UI isn’t updating, confirm SSE is connected (GET /api/events). See docs/help/sse.md.
• If you’re working on REST handlers, use docs/help/api-quick-reference.md and keep docs/openapi.json in sync for contract changes.
• When chasing server behavior, enable logs:
  • RUST_LOG=debug cargo run -- serve --port 8080

Visual verification (browser + vision)

Follow review-handoff for browser/screenshot evidence.
For manual scenarios use npm run seed:test-tasks -- --serve; for durable proof
add a smoke test. Start long-running servers using the harness's managed process
facility, or a dedicated terminal if unavailable, and stop only processes you own.

Safety

• Treat .env* and local config as sensitive; don’t paste secrets/PII into logs/issues.