fix: resolve 6 installation bugs breaking fresh setup

[rohitg00]

Summary

Fresh npm install and Docker-based installs were completely broken. Reported by Vinuja who hit all 3 failure modes.

• zod peer dep conflict: @anthropic-ai/claude-agent-sdk@0.2.56 requires zod@^4.0.0 but we had ^3.23.0 — npm install fails with ERESOLVE
• Docker missing config: docker-compose.yml didn't mount iii-config.yaml into the container — iii-engine crashes with "Config file not found: /app/config.yaml"
• Docker host binding: host: 127.0.0.1 in iii-config.yaml only listens on container loopback — Docker port mapping can't reach the engine
• npm start infinite loop: ran index.mjs directly (no engine auto-start) — users get endless WebSocket reconnection errors
• CLI health check false negative: checked /agentmemory/livez which requires a registered worker — returns 404 even when engine is running, so CLI thinks engine is down
• Viewer EADDRINUSE crash: port conflict on 3113 crashes the entire process instead of logging a warning

Also fixes README step numbering (was 1,2,4) and outdated version in health example.

Test plan

• npm install resolves cleanly (no ERESOLVE)
• npm run build succeeds
• All 627 tests pass
• npm start detects running iii-engine and starts worker
• /agentmemory/health returns healthy status
• /agentmemory/livez returns ok
• Viewer EADDRINUSE logs warning instead of crashing
• Docker: docker compose up starts iii-engine with config (needs Docker environment)

Summary by CodeRabbit

• Documentation

  • Updated version reference in README examples.

• Configuration

  • Services now listen on all network interfaces (0.0.0.0) for improved accessibility.
  • Added support for external config file mounting in Docker deployments.
  • Enhanced error handling with clear messaging when configured ports are already in use.

• Chores

  • Updated zod validation library to v4.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates deployment configuration and application entry points. Changes include shifting network listeners to 0.0.0.0, introducing a config file bind mount in Docker, modifying the start script entrypoint, updating the health probe endpoint, adding HTTP server error handling, and bumping documentation version and dependencies.

Changes

Cohort / File(s)	Summary
Configuration & Networking docker-compose.yml, iii-config.yaml	Added read-only bind mount for config file in container; updated REST API and Stream module listening addresses from 127.0.0.1 to 0.0.0.0 to accept external connections.
Runtime & Dependencies package.json, src/cli.ts	Changed start script entrypoint from dist/index.mjs to dist/cli.mjs; updated health check probe from /agentmemory/livez to / and simplified liveness logic; bumped zod dependency to ^4.0.0.
Error Handling src/viewer/server.ts	Added HTTP server error handler that logs warnings for EADDRINUSE (port already in use) and errors for other failure conditions before listening begins.
Documentation README.md	Renumbered Quick Start verification step from "4" to "3"; updated example health response version from 0.7.1 to 0.7.4.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Poem

🐰 Through config fields the bindings leap,
Listeners now broadcast far and deep,
With 0.0.0.0 the net expands wide,
New error caught with graceful pride—
This rabbit cheers the changes true! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: resolve 6 installation bugs breaking fresh setup' directly and specifically summarizes the main objective of the PR, which is to fix multiple installation-related bugs.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/installation-bugs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

iii-config.yaml (1)

13-37: ⚠️ Potential issue | 🟠 Major

0.0.0.0 binding broadens external exposure by default.

With Docker-published ports, exposing both REST and stream modules on all interfaces makes them reachable beyond localhost unless deployment constraints are added. Please pair this with host-side loopback port publishing (or strict auth defaults) to avoid accidental network exposure.

🔧 Suggested hardening (in docker-compose.yml)

 services:
   iii-engine:
     ports:
-      - "3111:3111"
-      - "3112:3112"
+      - "127.0.0.1:3111:3111"
+      - "127.0.0.1:3112:3112"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@iii-config.yaml` around lines 13 - 37, The config currently binds services to
0.0.0.0 (global host entry and the StreamModule's host) which exposes REST and
stream ports externally; change those host values to 127.0.0.1 (or another
internal-only interface) for the global host key and the StreamModule host
config, or alternatively ensure your deployment (docker-compose) uses
loopback-only port publishing and strict auth—locate the global "host" key and
the "class: modules::stream::StreamModule" block (the StreamModule's "host" and
"port" settings) and update them to restrict binding to localhost or document
the required Docker publish behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@iii-config.yaml`:
- Around line 13-37: The config currently binds services to 0.0.0.0 (global host
entry and the StreamModule's host) which exposes REST and stream ports
externally; change those host values to 127.0.0.1 (or another internal-only
interface) for the global host key and the StreamModule host config, or
alternatively ensure your deployment (docker-compose) uses loopback-only port
publishing and strict auth—locate the global "host" key and the "class:
modules::stream::StreamModule" block (the StreamModule's "host" and "port"
settings) and update them to restrict binding to localhost or document the
required Docker publish behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec1de863-f31b-425f-9460-e86d6a1a6a57

📥 Commits

Reviewing files that changed from the base of the PR and between 1fa0dce and 9283720.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• README.md
• docker-compose.yml
• iii-config.yaml
• package.json
• src/cli.ts
• src/viewer/server.ts