Restart and health checks

Use this page when you need to restart a development instance, confirm which port it is using, or prove that the backend is healthy after a code change.

Local restart

Run the canonical restart command from the repository root:

./restart.sh

The script delegates to the same startup path used by the project scripts. It loads local environment values, resolves a worktree-aware port, starts the backend, and waits for the health endpoint to respond.

Multiple worktrees

The main checkout normally uses port 8888. Additional git worktrees should use their own ports so local development sessions do not interrupt each other.

bash scripts/status.sh

Use the status script to confirm which checkout owns each local instance before you restart or stop a process.

Override the port

Set JARVIS_PORT in the local environment file when a checkout needs a fixed port:

echo "JARVIS_PORT=9999" >> .env
./restart.sh

Use this only for the checkout you are actively running. Do not reuse the main port across independent worktrees.

Verify health

After restart, call the health endpoint:

curl -s http://127.0.0.1:${JARVIS_PORT:-8888}/api/v1/health

The response should be JSON and include a healthy status plus the version that you intended to run.

Common failures

Symptom	Likely cause	First action
Health check returns HTML	Wrong endpoint path	Use `/api/v1/health`, not `/health`.
Port is already in use	Another local instance owns the port	Run `bash scripts/status.sh` and stop the right checkout.
Frontend looks stale	The static frontend bundle is old	Rebuild `frontend/` and hard refresh the browser.
Backend starts but UI cannot authenticate	Browser has an old API key	Generate a fresh key and paste it into the UI.