Honor an already-configured self-host server_url/app_url when re-running `multica setup self-host` without flags, instead of silently resetting to http://localhost:8080. The existing config is added as a fallback step in the URL resolution chain (flag → env → existing config → localhost), and the overwrite confirmation now shows URL changes as `old -> new`.
Closes#4536
MUL-3660
## Summary
- expose `--callback-host` on `multica setup` and `multica setup cloud`, reusing the existing login callback override
- print an SSH tunnel hint when browser login runs in an SSH session with a loopback callback
- show local flags in parent-command help so `multica setup --help` documents the callback option
Fixes#4357
## Tests
- `go test ./cmd/multica -run 'TestCallbackHostFlagValueReadsParentSetupFlag|TestSetupHelpShowsCallbackHostFlag|TestSetupCallbackHostFlagWiring|TestBrowserLoginInstructionsSSHRemoteHint'`
- `go run ./cmd/multica setup --help`
- `go run ./cmd/multica setup cloud --help`
- `git diff --check`
- `go test ./...`
* fix(cli): honor MULTICA_SERVER_URL in setup self-host
`multica setup self-host` resolved the backend URL only from the
--server-url flag, falling back to http://localhost:8080 when the flag
was absent. It never consulted MULTICA_SERVER_URL, even though that env
var is documented on the root --server-url flag and in `multica --help`,
and is honored by every other command via resolveServerURL. A self-host
user who set the env var instead of the flag still hit localhost and got
"Server at http://localhost:8080 is not reachable".
Route server-url and app-url through cli.FlagOrEnv so the documented env
vars (MULTICA_SERVER_URL / MULTICA_APP_URL) are honored when the matching
flag is not set, with the flag still taking precedence. userProvided now
reflects flag-or-env, so an env-sourced remote URL still triggers the
explicit app_url prompt. Not platform-specific despite the report.
Fixes GitHub #3912.
Co-authored-by: multica-agent <github@multica.ai>
* fix(cli): normalize MULTICA_SERVER_URL in setup self-host
MULTICA_SERVER_URL is documented as a ws:// daemon address
(ws://localhost:8080/ws) and every other command normalizes it via
NormalizeServerBaseURL before use. setup self-host consumed the resolved
value raw and probed <url>/health, so a self-hoster who set the
documented ws:// form would still fail the reachability check.
Run the flag/env value through normalizeAPIBaseURL (ws->http, wss->https,
strip /ws) so the documented form works and the stored server_url stays a
clean http(s) base. Add a normalization test case and a focused test for
the MULTICA_APP_URL env path (review nit).
Co-authored-by: multica-agent <github@multica.ai>
* docs(self-host): note setup self-host honors MULTICA_SERVER_URL / MULTICA_APP_URL
Document that `setup self-host` reads the env vars when the matching flag
is omitted (flag wins), and that MULTICA_SERVER_URL accepts the ws://…/ws
daemon form. Added to en/zh/ja/ko quickstart for parity.
Co-authored-by: multica-agent <github@multica.ai>
---------
Co-authored-by: J <j@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
* fix(server): recognize official cloud by frontend host in daemon setup config
The 'Add a computer' dialog builds its command from /api/config's
daemon_server_url/daemon_app_url, falling back to 'multica setup' when
both are empty. The official cloud is meant to omit them, but the
omission only fired when MULTICA_PUBLIC_URL=https://api.multica.ai. When
that env is unset the server URL defaults to the frontend origin and the
old guard (which required serverURL host == api.multica.ai) didn't match,
so the dialog emitted 'multica setup self-host --server-url
https://multica.ai' — pointing the daemon backend at the frontend (no
/health, no WebSocket proxy).
Identify the official cloud by its frontend host alone (multica.ai /
app.multica.ai) so a missing or misconfigured MULTICA_PUBLIC_URL can no
longer leak the broken self-host command. Regression from #3474.
* fix(cli): probe before persisting self-host config to preserve auth on failure
setup self-host wrote a fresh CLIConfig{ServerURL, AppURL} (a full
overwrite that drops the saved token) and only then probed the server,
returning early on failure. A failed probe therefore logged the user out
and left them unconnected, with no recovery in the same command.
Probe first via persistSelfHostConfigIfReachable: an unreachable server
leaves the existing config — and its token — untouched (failed setup =
no-op). The prober is injected so both branches are unit-tested.
* fix(daemon): serve health before preflight so daemon start readiness is accurate
The CLI's 'daemon start' polls the health endpoint for 15s expecting
status=running, but the daemon only began serving health after
preflightAuth, whose initial workspace sync detects every configured
agent's version by exec'ing it (~20s cold with 8 agents). Health served
too late, so a perfectly healthy daemon printed 'may not have started
successfully'.
Start the health server right after resolveAuth (which still fails fast
on a missing token) and before the slow preflight, so readiness reflects
the daemon core being up rather than agent-version detection finishing.
* fix(daemon): gate /health readiness so daemon start can't report a false start
Serving health before preflightAuth fixed the false-negative (a healthy
daemon printed "may not have started"), but health still returned
status:"running" unconditionally — before preflight (PAT renew + workspace
sync + runtime registration) had completed. `daemon start` and the desktop
treat "running" as ready, so a slow or *failing* preflight could be
misreported as a started daemon: setup prints "connected", then the process
exits or hangs in agent-version detection with no runtime registered. That
is harder to diagnose than the original false-negative.
Split liveness from readiness: bind/serve the health port early (so callers
see a live "starting" daemon instead of connection-refused), but report
status:"starting" until d.ready is set after preflight, then "running".
- daemon.go: add d.ready (atomic.Bool); set it true after the background
loops launch, before pollLoop.
- health.go: healthHandler reports "starting" until ready, else "running".
- cmd_daemon.go: `daemon start` waits for "running" with a deadline raised
to 45s (covers cold-start agent detection) and a clearer "still starting"
message; new daemonAlive() helper treats both "running" and "starting" as
a live daemon, so the already-running guard, restart, and stop act on a
starting daemon and don't double-spawn or race its listener; `daemon
status` shows "starting" distinctly.
Older CLIs/desktop that only know "running" safely treat "starting" as
not-ready (status != "running"), so no boundary break.
Tests: health reports starting-then-running; daemonAlive truth table.
Co-authored-by: multica-agent <github@multica.ai>
* fix(desktop): handle daemon "starting" health status in lifecycle
The daemon now reports /health status:"starting" until preflight completes
(liveness/readiness split). That made "starting" a new external contract of
/health, but the Desktop daemon-manager only knew "running", so the readiness
fix would have moved the CLI's false-negative into a Desktop start regression:
- `daemon start` now blocks up to 45s waiting for readiness, but the Desktop
spawned it via execFile({ timeout: 20_000 }). On a cold start (the ~20s agent
detection this PR targets) Electron killed the CLI supervisor at 20s and
reported a start failure, even though the detached daemon child kept booting —
the UI flashed "stopped" then "running". Raise the timeout to 60s (must exceed
the CLI's 45s startupTimeout).
- The Desktop treated only raw status === "running" as a live daemon, so a
daemon that was still "starting" (booting on its own or started via the CLI)
showed as "stopped", and startDaemon() would spawn a second one — which the new
CLI rejects as "already running", surfacing as a start error.
Add daemonStatusAlive() (shared, pure, unit-tested) mirroring the Go daemonAlive()
and use it for liveness: fetchHealth() surfaces a daemon-reported "starting" as
state "starting" regardless of our own currentState; startDaemon()'s
already-running guard and the restart-on-user-switch guard treat "starting" as an
existing daemon. version-decision stays gated on "running" (readiness, not
liveness) — unchanged.
Verified: desktop typecheck, eslint, full vitest suite (193 tests) all pass.
Co-authored-by: multica-agent <github@multica.ai>
---------
Co-authored-by: J <j@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
* fix(cli): make browser-login work from a machine that isn't the server
The #923 callback host fix only worked when the CLI and the self-hosted
server ran on the same box. In a cross-machine setup — `multica login`
from a laptop against a self-hosted server on a NAS — the flow silently
wedged on two issues:
1. The callback host was derived from `--app-url`, so the `cli_callback`
URL pointed at the server's IP and the browser could never reach
the CLI's local listener on the laptop. The OAuth token never came
back and subsequent `/api/workspaces` calls 401'd on stale state.
2. `net.Listen("tcp", ...)` on macOS can produce an IPv6-only socket.
Browsers and `curl` resolve `localhost`/`127.0.0.1` to IPv4 first and
get "connection refused" even when the URL is otherwise correct.
Changes:
- Derive the callback host from the CLI's own outbound interface by
dialing the server (UDP, no packets sent — just asks the kernel which
source IP it would use). Falls back to loopback for public app URLs
and to the app IP for offline detection.
- Add `--callback-host` flag on `login` and `setup self-host` so
reverse-proxy / FQDN users can override auto-detection — this is the
follow-up @hassaanz asked for on #923.
- Pin the callback listener to `tcp4` so macOS never lands on an
IPv6-only socket.
- `multica setup self-host`: when the user explicitly passes a remote
`--server-url` but omits `--app-url`, infer app URL from the server
host and warn instead of silently defaulting to `localhost:3000`.
Unit tests cover the binding-decision matrix (public, localhost, same-
machine LAN, cross-machine LAN, outbound-detect failure, flag override)
and the new setup helpers.
Reported by @RafeRoberts in #1494 with very clear repro details.
* fix(cli): prompt for app_url instead of guessing on remote server_url
Per GPT-Boy's review on MUL-1260: deriving app_url as
http://<server-host>:3000 breaks for the common api.example.com +
app.example.com split and for https-fronted deploys — the setup flow
would still open a broken login URL, just slightly later.
Replace the guess with an interactive prompt. If the user hits enter
(or stdin is unavailable), fail loudly with a clear usage hint instead
of proceeding with bad data.
The daemon now automatically watches all workspaces the user belongs to,
fetched directly from the API. This removes the manual watch/unwatch
workflow, the config-based watched/unwatched lists, the /watch HTTP
endpoints, the CLI watch/unwatch commands, and the desktop app's watched
workspace UI and reconciliation logic.
Co-authored-by: Devv <devv@Devvs-Mac-mini.local>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): auto-create workspace for new users during setup
When a new user runs `multica setup` and has no workspaces,
the onboarding flow now auto-creates a default workspace
(named "<name>'s Workspace") instead of failing when the
daemon tries to start with zero watched workspaces.
As a safety net, setup commands also skip daemon start
gracefully if no workspaces are configured, instead of
erroring out.
* fix(cli): redirect to web onboarding instead of auto-creating workspace
When no workspaces exist, the CLI now opens the web onboarding wizard
in the browser and polls until the user completes workspace creation.
This reuses the existing 4-step onboarding flow (workspace → runtime →
agent → done) instead of duplicating creation logic in the CLI.
* fix(cli): address code review — token login crash and misleading success msg
1. Token login (`multica login --token`) on a fresh account no longer
crashes: waitForOnboarding uses tryResolveAppURL (returns "" instead
of os.Exit(1)) and falls back to printing manual instructions.
2. Setup commands no longer print "✓ Setup complete!" when onboarding
was not finished. Shows "⚠ Setup incomplete" with next steps instead.
Decouple install.sh from environment configuration — install.sh now only
installs the CLI binary (and optionally Docker via --with-server), while
all environment configuration moves to `multica setup` subcommands.
Key changes:
- install.sh: remove config writes, rename --local to --with-server
- multica setup: add cloud/self-host subcommands with --server-url,
--app-url, --port, --frontend-port flags and --profile support
- Add config overwrite protection with interactive prompt
- Remove redundant commands: `config local`, `auth login` alias
- Replace silent multica.ai fallbacks with explicit errors
- Onboarding wizard: dynamically show correct setup command for
Cloud vs Self-host environments
- Update all docs, landing page, and install scripts for consistency
After installing via `curl | bash` (default/cloud mode) or running
`multica setup` without a local server, the CLI config could retain
stale localhost URLs from a previous `multica config local` or
`--local` install. This caused `multica login` to connect to
localhost instead of multica.ai.
Fix: explicitly write cloud URLs (api.multica.ai / multica.ai) to
the config in both the install script's cloud mode and the setup
command's cloud fallback path.
