Conversation
…nd JSDoc (#1152) The server's getPort() fallback changed from 3000 to 3090 in the Hono migration (#318), but .env.example, the setup wizard's generated .env, and the JSDoc describing the fallback were not updated — leaving three different sources of truth for "the default PORT." When the wizard writes PORT=3000 to ~/.archon/.env (which the Hono server loads with override: true, while Vite only reads repo-local .env), the two processes can land on different ports silently. That mismatch is the real mechanism behind the failure described in #1152. - .env.example: comment out PORT, document 3090 as the default - packages/cli/src/commands/setup.ts: wizard no longer writes PORT=3000 into the generated .env; fix the "Additional Options" note - packages/cli/src/commands/setup.test.ts: assert no bare PORT= line and the commented default is present - packages/core/src/utils/port-allocation.ts: fix stale JSDoc "default 3000" -> "default 3090" - deploy/.env.example: keep Docker default at 3000 (compose/Caddy target that) but annotate it so users don't copy it for local dev Single source of truth for the local-dev default is now basePort in port-allocation.ts.
📝 WalkthroughWalkthroughThe pull request updates the default server port from 3000 to 3090 across configuration examples, CLI setup generation, tests, and utility documentation. Changes include commented environment file entries with guidance and updated test expectations to reflect the new default behavior. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@deploy/.env.example`:
- Line 49: The PORT line in the .env example contains an inline comment which
will be interpreted as part of the value by Docker Compose; change the env line
to a plain assignment "PORT=3000" (no trailing comment) and move the explanatory
guidance into its own comment line above (e.g., "# Docker deployment default
(compose/Caddy target :3000). For local dev omit PORT — server and Vite proxy
default to 3090."). Ensure references that rely on this value such as the
docker-compose port mapping "${PORT:-3000}:${PORT:-3000}" and the healthcheck
URL "http://localhost:${PORT:-3000}/api/health" will receive a clean numeric
PORT value.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a04d075e-484e-43ef-b1e8-5ab9443ca7dc
📒 Files selected for processing (5)
.env.exampledeploy/.env.examplepackages/cli/src/commands/setup.test.tspackages/cli/src/commands/setup.tspackages/core/src/utils/port-allocation.ts
| # Optional | ||
| # ============================================ | ||
| PORT=3000 | ||
| PORT=3000 # Docker deployment default (the included compose/Caddy configs target :3000). For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Does Docker Compose env_file support inline # comments on the same line as KEY=VALUE, and in which version was this added?
💡 Result:
No, Docker Compose env_file does not support inline # comments on the same line as KEY=VALUE. env_file files are parsed as raw KEY=VALUE pairs by the Docker CLI, which only supports line comments starting with #, not inline comments. This matches the behavior of docker run --env-file, and changing it would break backward compatibility. Inline comments (e.g., KEY=VALUE # comment) are supported in the Compose CLI's .env file (used for variable interpolation in compose.yaml), but not in env_file. This distinction has been consistent, as confirmed in official docs and GitHub issues. The syntax rules for .env files explicitly describe inline comments with a space before # for unquoted values, but env_file uses a simpler parser without this feature.
Citations:
- 1: https://docs.docker.com/compose/env-file/
- 2: https://docs.docker.com/compose/environment-variables/env-file/
- 3: https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/
- 4: https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
- 5: https://docs.docker.com/compose/env
- 6: https://docs.docker.com/compose/environment-variables/set-environment-variables
- 7: https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables
- 8:
--env-filedoesn't support inline comments docker/cli#4404 - 9: Inline comments in
.envdocker/compose#9025
🏁 Script executed:
fd -type f -name "docker-compose.yml" -o -name "docker-compose.yaml" | head -20Repository: coleam00/Archon
Length of output: 229
🏁 Script executed:
if git ls-files | grep -E "(docker-compose|compose)" | head -20; then :; fiRepository: coleam00/Archon
Length of output: 182
🏁 Script executed:
cat -n deploy/docker-compose.yml | head -100Repository: coleam00/Archon
Length of output: 1780
Inline comments on PORT=3000 will break Docker Compose env_file parsing.
Docker Compose's env_file parser does not support inline comments—the entire text after = is treated as the value, so a line like PORT=3000 # Docker deployment default... results in PORT being set to 3000 # Docker deployment default... instead of 3000. This breaks the ${PORT:-3000}:${PORT:-3000} port mapping and the http://localhost:${PORT:-3000}/api/health healthcheck. Move the guidance onto its own comment line:
🔒 Proposed fix
-PORT=3000 # Docker deployment default (the included compose/Caddy configs target :3000). For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090.
+# Docker deployment default (the included compose/Caddy configs target :3000).
+# For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090.
+PORT=3000📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| PORT=3000 # Docker deployment default (the included compose/Caddy configs target :3000). For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090. | |
| # Docker deployment default (the included compose/Caddy configs target :3000). | |
| # For local dev (no Docker), omit PORT — server and Vite proxy both default to 3090. | |
| PORT=3000 |
🧰 Tools
🪛 dotenv-linter (4.0.0)
[warning] 49-49: [ValueWithoutQuotes] This value needs to be surrounded in quotes
(ValueWithoutQuotes)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@deploy/.env.example` at line 49, The PORT line in the .env example contains
an inline comment which will be interpreted as part of the value by Docker
Compose; change the env line to a plain assignment "PORT=3000" (no trailing
comment) and move the explanatory guidance into its own comment line above
(e.g., "# Docker deployment default (compose/Caddy target :3000). For local dev
omit PORT — server and Vite proxy default to 3090."). Ensure references that
rely on this value such as the docker-compose port mapping
"${PORT:-3000}:${PORT:-3000}" and the healthcheck URL
"http://localhost:${PORT:-3000}/api/health" will receive a clean numeric PORT
value.
Collaborator
PR Review Summary (multi-agent)Reviewed with Critical IssuesNone. Important Issues (2 found)
Suggested replacement for // PORT is intentionally omitted so both the server and Vite proxy independently default
// to 3090, keeping them in sync regardless of which .env files each process reads.Suggestions (4 found)
Strengths
Documentation IssuesNone — independent scan of VerdictNEEDS MINOR FIXES — the CLAUDE.md comment-rule violations (two Recommended Actions
|
Wirasm
added a commit
that referenced
this pull request
Apr 17, 2026
Applies the CLAUDE.md comment rule ("don't embed paths/callers that rot
as the codebase evolves") flagged by the PR #1271 review to the Pi
provider's inline comments.
Three spots in the merged Pi code embed `packages/.../provider.ts:N-M`
line ranges pointing at the Claude and Codex providers. These ranges
will drift the moment those files change — the Claude auth-merge
pattern's line numbers are already off-by-a-few in some local branches.
Keep the conceptual cross-reference ("mirrors Claude's process-env +
request-env merge pattern", "matches the Codex provider's fallback
pattern for the same condition") — that's the load-bearing part of the
comment — drop the fragile line numbers and file paths.
Same treatment for the upstream Pi auth-storage.ts:424-485 reference,
which points at a specific line range in a moving dependency.
No behavior change; comment-only refactor.
1 task
Wirasm
added a commit
that referenced
this pull request
Apr 17, 2026
…nts (#1275) Applies the CLAUDE.md comment rule ("don't embed paths/callers that rot as the codebase evolves") flagged by the PR #1271 review to the Pi provider's inline comments. Three spots in the merged Pi code embed `packages/.../provider.ts:N-M` line ranges pointing at the Claude and Codex providers. These ranges will drift the moment those files change — the Claude auth-merge pattern's line numbers are already off-by-a-few in some local branches. Keep the conceptual cross-reference ("mirrors Claude's process-env + request-env merge pattern", "matches the Codex provider's fallback pattern for the same condition") — that's the load-bearing part of the comment — drop the fragile line numbers and file paths. Same treatment for the upstream Pi auth-storage.ts:424-485 reference, which points at a specific line range in a moving dependency. No behavior change; comment-only refactor.
ztech-gthb
pushed a commit
to ztech-gthb/Archon
that referenced
this pull request
Apr 18, 2026
…nts (coleam00#1275) Applies the CLAUDE.md comment rule ("don't embed paths/callers that rot as the codebase evolves") flagged by the PR coleam00#1271 review to the Pi provider's inline comments. Three spots in the merged Pi code embed `packages/.../provider.ts:N-M` line ranges pointing at the Claude and Codex providers. These ranges will drift the moment those files change — the Claude auth-merge pattern's line numbers are already off-by-a-few in some local branches. Keep the conceptual cross-reference ("mirrors Claude's process-env + request-env merge pattern", "matches the Codex provider's fallback pattern for the same condition") — that's the load-bearing part of the comment — drop the fragile line numbers and file paths. Same treatment for the upstream Pi auth-storage.ts:424-485 reference, which points at a specific line range in a moving dependency. No behavior change; comment-only refactor.
ztech-gthb
pushed a commit
to ztech-gthb/Archon
that referenced
this pull request
Apr 18, 2026
…nd JSDoc (coleam00#1152) (coleam00#1271) The server's getPort() fallback changed from 3000 to 3090 in the Hono migration (coleam00#318), but .env.example, the setup wizard's generated .env, and the JSDoc describing the fallback were not updated — leaving three different sources of truth for "the default PORT." When the wizard writes PORT=3000 to ~/.archon/.env (which the Hono server loads with override: true, while Vite only reads repo-local .env), the two processes can land on different ports silently. That mismatch is the real mechanism behind the failure described in coleam00#1152. - .env.example: comment out PORT, document 3090 as the default - packages/cli/src/commands/setup.ts: wizard no longer writes PORT=3000 into the generated .env; fix the "Additional Options" note - packages/cli/src/commands/setup.test.ts: assert no bare PORT= line and the commented default is present - packages/core/src/utils/port-allocation.ts: fix stale JSDoc "default 3000" -> "default 3090" - deploy/.env.example: keep Docker default at 3000 (compose/Caddy target that) but annotate it so users don't copy it for local dev Single source of truth for the local-dev default is now basePort in port-allocation.ts.
joaobmonteiro
pushed a commit
to joaobmonteiro/Archon
that referenced
this pull request
Apr 26, 2026
…nts (coleam00#1275) Applies the CLAUDE.md comment rule ("don't embed paths/callers that rot as the codebase evolves") flagged by the PR coleam00#1271 review to the Pi provider's inline comments. Three spots in the merged Pi code embed `packages/.../provider.ts:N-M` line ranges pointing at the Claude and Codex providers. These ranges will drift the moment those files change — the Claude auth-merge pattern's line numbers are already off-by-a-few in some local branches. Keep the conceptual cross-reference ("mirrors Claude's process-env + request-env merge pattern", "matches the Codex provider's fallback pattern for the same condition") — that's the load-bearing part of the comment — drop the fragile line numbers and file paths. Same treatment for the upstream Pi auth-storage.ts:424-485 reference, which points at a specific line range in a moving dependency. No behavior change; comment-only refactor.
joaobmonteiro
pushed a commit
to joaobmonteiro/Archon
that referenced
this pull request
Apr 26, 2026
…nd JSDoc (coleam00#1152) (coleam00#1271) The server's getPort() fallback changed from 3000 to 3090 in the Hono migration (coleam00#318), but .env.example, the setup wizard's generated .env, and the JSDoc describing the fallback were not updated — leaving three different sources of truth for "the default PORT." When the wizard writes PORT=3000 to ~/.archon/.env (which the Hono server loads with override: true, while Vite only reads repo-local .env), the two processes can land on different ports silently. That mismatch is the real mechanism behind the failure described in coleam00#1152. - .env.example: comment out PORT, document 3090 as the default - packages/cli/src/commands/setup.ts: wizard no longer writes PORT=3000 into the generated .env; fix the "Additional Options" note - packages/cli/src/commands/setup.test.ts: assert no bare PORT= line and the commented default is present - packages/core/src/utils/port-allocation.ts: fix stale JSDoc "default 3000" -> "default 3090" - deploy/.env.example: keep Docker default at 3000 (compose/Caddy target that) but annotate it so users don't copy it for local dev Single source of truth for the local-dev default is now basePort in port-allocation.ts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Failed to load conversations/projectswithECONNREFUSEDin the Vite log. Reported in bug(setup): fresh install on Windows 11 leaves web UI broken — .env not created, server (:3000) and Vite proxy (:3090) default to different ports #1152.PORT=3000from the wizard-generated.env, comment it out in.env.example, fix the stale JSDoc"default 3000"inport-allocation.ts, and update the wizard's "Additional Options" note.deploy/.env.examplekeepsPORT=3000(Docker compose/Caddy target it) but now carries a comment so someone copying it for local dev won't be silently misled.basePort(still 3090, the current code default), no change to Vite's fallback (already 3090, correct), no change to the Hono server's dual-.envloading (repo/.env+~/.archon/.envwithoverride: true). The underlying asymmetry (Hono reads both, Vite reads only repo-local) is discussed but intentionally left alone — narrowing the fix to the three drift points that are safe to align.UX Journey
Before
After
Architecture Diagram
Before
After
Connection inventory:
.env.env(repo + ~/.archon)apiPortgetPort()Label Snapshot
risk: lowsize: XScliconfigdocscli:setup,core:port-allocationChange Metadata
bugcliLinked Issue
basePortbecame 3090)Validation Evidence (required)
E2E verified on this branch (with
.envtemporarily removed, fresh-clone scenario):Pre-existing failing test in
packages/workflows/src/defaults/bundled-defaults.test.tsis unrelated — caused by an untracked.archon/workflows/defaults/archon-feedback.yamlin my local working tree, not by any change in this PR.Security Impact (required)
NoNoNoNoCompatibility / Migration
Yes— existing users withPORT=3000explicitly set in their.envkeep that behavior (explicit PORT always wins at server and Vite). Only unset/new installs switch to 3090.Yes—.env.exampledefault commented out. Existing.envfiles on disk are untouched.No~/.archon/.envfrom an earlierarchon setupcontinue to work; the explicitPORT=3000there still takes effect. To move onto the 3090 default they can delete thePORT=line.Human Verification (required)
.envanywhere: server binds 3090, Vite proxies 5173 → 3090,/api/healthreturns 200 through the proxy.@archon/clitests pass with the updatedgenerateEnvContentassertions.PORT=3000in.env— unchanged (explicit value wins at both server and Vite).deploy/.env.exampleto repo root — now sees the comment explaining it is a Docker default.bun run validatewas blocked by a pre-existing bundled-defaults drift unrelated to this change (an untracked file in my local tree); the individual validation steps all pass.deploy/.env.exampleis a text-only change).Side Effects / Blast Radius (required)
archon setupwizard output (.envgeneration) — no longer writes an explicit PORT line by default..env.exampleread by anyone copying it as a starting point — they no longer start on 3000 unless they uncomment.setup.test.tsasserts both positive (# PORT=3090present) and negative (no uncommentedPORT=line) conditions — catches any regression that reintroduces a hardcoded PORT.Rollback Plan (required)
git revert <merge-sha>— commit is small and self-contained.archon setup, check whether their~/.archon/.envstill hasPORT=3000written by a pre-revert wizard run.Risks and Mitigations
Risk: Users with an existing stale
~/.archon/.envcontainingPORT=3000(from a prior wizard run) continue to see server bind on 3000 while Vite proxies to 3090 — the original bug persists for them.PORT=line from their global.env.Risk: Downstream docs might still reference
:3000as "the" default.packages/docs-web/src/content/docs/already documents the 3090-local / 3000-Docker split correctly (via Fix failing react tests #318 follow-ups). No further doc changes needed in this PR.Summary by CodeRabbit
PORTconfiguration will automatically use the new default. If you previously relied on port 3000, you may need to adjust your environment configuration or explicitly setPORT=3000in your.envfile.