Turn Document · June 13, 2026

# Configure Local Web and Desktop Development for the Hosted API

Branch lavender/configure-hosted-api-endpoint
Issue islandflow-7l2
API Host https://api.flow.deltaisland.io
App Host https://flow.deltaisland.io

## Summary

Local web development and the desktop local-UI workflow now default API and WebSocket traffic to `https://api.flow.deltaisland.io`, while the hosted desktop window still opens the app at `https://flow.deltaisland.io`.

## Changes Made

- Added a local web development default API origin in `apps/web/scripts/dev.ts`.
- Changed `scripts/dev-desktop.ts` so its spawned local web UI uses the API subdomain by default.
- Updated README guidance for web and desktop development to distinguish the hosted app origin from the hosted API origin.
- Updated the ignored local file `apps/web/.env.local` on this machine to point at the API subdomain. That local file is not committed.

## Context

The VPS check over `ssh di` confirmed `https://api.flow.deltaisland.io/health` returns `200`, while `https://flow.deltaisland.io/health` returns `404`. The app origin remains the hosted UI, and the API subdomain is the correct base for local dev API and WebSocket calls.

## Important Implementation Details

- `bun run dev:web` now passes `NEXT_PUBLIC_API_URL` into Next.js when the variable is not already set.
- `bun run dev:desktop` still launches Electron at `http://127.0.0.1:3000`, but the local web child receives the hosted API origin.
- `bun run dev:desktop:remote` still loads `https://flow.deltaisland.io` directly and does not start the local web child.

## Relevant Diff Snippets

Rendered with `@pierre/diffs/ssr` from the focused endpoint patch and contained in an offline iframe.

## Expected Impact for End-Users

Running local web or desktop development should reach the live Delta Island API without manually remembering the current API hostname. Hosted desktop behavior stays pointed at the public app.

## Validation

- `ssh di` plus curl confirmed `api.flow.deltaisland.io/health` responds with `200`.
- `bun run scripts/check-public-api-routes.ts https://api.flow.deltaisland.io` passed for REST and WebSocket probes.
- `bun test apps/web/app/terminal.test.ts apps/web/app/api/admin/synthetic/routes.test.ts apps/desktop/src/security.test.ts` passed.
- `bun --cwd=apps/web run build` passed.
- A brief `bun run dev:web` smoke confirmed the API origin is `https://api.flow.deltaisland.io`, but port `3000` was already occupied by an existing `node` listener.

## Issues, Limitations, and Mitigations

- The smoke run could not bind port `3000` because another local process was already listening there. The startup log still confirmed the corrected API origin.
- The local ignored `apps/web/.env.local` change fixes this machine only. Tracked script defaults cover missing local env files for future worktrees.
- Unrelated dashboard route edits were present in the worktree before this endpoint fix and were not included in this task's intended patch.

## Follow-up Work

No endpoint follow-up is required. The existing port `3000` listener can be stopped separately if the user wants a clean local dev server restart.