Summary
agentuity dev always injects PORT=<--port> (default 3000) into the child dev process. Projects whose dev script manages its own listen ports (split frontend/API, custom Vite proxy layout) get a misleading banner and Gravity tunnels the wrong port unless the caller remembers --port.
Genesis v3 (apps/web) runs Vite on 3500 and Bun API on 3501 via scripts/dev.sh, which explicitly unset PORT before starting the API. Gravity and the CLI dev banner still target whatever was passed to --port (or 3000 by default).
Repro (Genesis)
cd apps/web
bun run dev:agentuity # without --port 3500
- CLI sets
PORT=3000 and starts Gravity against port 3000 when --public is enabled.
- Actual UI is at
http://127.0.0.1:3500; API at 3501.
- Public tunnel URL does not reach the Vite frontend unless
--port 3500 is passed manually.
Expected
One of:
- Do not inject
PORT when the project's dev script is known to manage ports (e.g. framework detection, or an agentuity.json dev port field).
- Read dev port from project config (e.g.
devmode.port or framework plugin metadata) instead of defaulting to 3000.
- Document split-port layouts and require explicit
--port for Gravity, but avoid implying the injected PORT is the app's primary URL when the dev script ignores it.
Workaround today
agentuity dev --no-interactive --port 3500 --public
Genesis wires this into dev:agentuity until SDK-side polish lands.
Context
- SDK 3.1.x:
packages/cli/src/cmd/dev/index.ts sets env.PORT = String(opts.port ?? DEFAULT_PORT) with DEFAULT_PORT = 3000.
- Gravity tunnel targets that same
port argument.
@agentuity/vite / devmode hostname env vars should align with the browser-facing port, not an unused injected PORT.
Suggested acceptance
- Split-port or multi-process dev scripts can opt out of automatic
PORT injection, or declare the Gravity target port in config.
- CLI banner and Gravity URL match the port users actually open in the browser.
- Backward compatible for single-port apps that listen on
process.env.PORT.
Summary
agentuity devalways injectsPORT=<--port>(default 3000) into the child dev process. Projects whosedevscript manages its own listen ports (split frontend/API, custom Vite proxy layout) get a misleading banner and Gravity tunnels the wrong port unless the caller remembers--port.Genesis v3 (
apps/web) runs Vite on 3500 and Bun API on 3501 viascripts/dev.sh, which explicitlyunset PORTbefore starting the API. Gravity and the CLI dev banner still target whatever was passed to--port(or 3000 by default).Repro (Genesis)
PORT=3000and starts Gravity against port 3000 when--publicis enabled.http://127.0.0.1:3500; API at3501.--port 3500is passed manually.Expected
One of:
PORTwhen the project's dev script is known to manage ports (e.g. framework detection, or anagentuity.jsondev port field).devmode.portor framework plugin metadata) instead of defaulting to 3000.--portfor Gravity, but avoid implying the injectedPORTis the app's primary URL when the dev script ignores it.Workaround today
Genesis wires this into
dev:agentuityuntil SDK-side polish lands.Context
packages/cli/src/cmd/dev/index.tssetsenv.PORT = String(opts.port ?? DEFAULT_PORT)withDEFAULT_PORT = 3000.portargument.@agentuity/vite/ devmode hostname env vars should align with the browser-facing port, not an unused injectedPORT.Suggested acceptance
PORTinjection, or declare the Gravity target port in config.process.env.PORT.