RFC: Optional remote backend mode (WSL2 daemon / native Windows UI)

[slkzgm]

Summary

I'd like to propose an optional "remote backend" mode that would allow CodexMonitor to run a small daemon on a Linux environment (e.g. WSL2), while keeping the UI as a native desktop app on Windows.

The key constraint is: Codex must keep running in the exact same environment (WSL2) for the same performance, access, tooling, and filesystem semantics — but the UI should not depend on WSLg/gWSL.

This would be opt-in and must not change default behavior for existing users.

Motivation (Windows + WSL2)

In a Windows 11 + WSL2 setup:

• Projects and tools live in WSL (/home/...), and codex is executed there.
• Running a Tauri Linux build through WSLg or gWSL works, but the UI can be janky/clunky and GPU permissions can be problematic.
• The best UX is a native Windows window (WebView2) while preserving a WSL-native codex runtime.

Additional use cases / benefits (beyond WSL)

Even without WSL, a remote backend mode could unlock:

• Remote Linux dev machines (SSH into a workstation/VM): native UI on the laptop/desktop without X forwarding/VNC.
• Devcontainers / sandboxes: run the backend inside a container/VM (where the repo, tools, and secrets live), while keeping the UI on the host.
• Long-running sessions: a supervised daemon (systemd) + UI reconnects after restarts/crashes without losing in-progress work.
• Future multi-client scenarios: groundwork for a read-only dashboard or a mobile companion UI later (still opt-in).
• Cleaner privilege boundaries: keep repo access + keys on the backend side; UI talks over localhost + token (local-only by default).

Goals

• Preserve the existing local backend mode (current behavior) as the default.
• Allow running the backend in another process/environment (e.g. WSL2) while the UI stays native.
• Keep the UI event stream and IPC surface stable.

Non-goals (initially)

• Solving path translation for every edge case.
• Supporting cross-machine networking by default.
• Large UX redesign.

Proposed direction

Add an optional daemon that:

• Runs locally (bind 127.0.0.1) and requires a token.
• Exposes the same high-level operations as the current backend (list_workspaces, connect_workspace, send_user_message, approvals, terminal PTY, etc.).
• Streams the same event payloads the UI already expects (e.g. app-server-event, terminal-output).

UI would gain a backend selector:

• Local (current)
• Remote (daemon) with URL + token

Incremental PR plan (no behavior change by default)

I'm proposing to split this into small PRs to reduce risk and improve acceptance.

PR1 (UI-only refactor, no-op)

• Introduce a src/services/events.ts module to centralize event subscriptions.
• Update hooks to use it (useAppServerEvents, useTerminalSession, etc.).
• No change in event names/payloads.

PR2 (Rust refactor, no-op)

• Separate backend "core" logic from Tauri glue to make it reusable.
• Keep the same #[tauri::command] surface and emitted events.

PR3 (optional daemon)

• Add a new binary (feature-gated if needed) that exposes a local-only API and event stream.

PR4 (remote backend mode)

• Add settings + connection logic.
• Keep default behavior unchanged.

PR5 (docs + CI)

• Document Windows+WSL flow.
• Ensure builds stay reasonable (feature flags, separate workflows).

Open questions / feedback wanted

• Preferred transport: WebSocket JSON-RPC vs REST+WS events?
• Where should the remote backend config live (app settings vs per-workspace)?
• How to handle file picker + image attachments in remote mode (WSL paths vs upload bytes)?
• Would maintainers accept the daemon as optional/feature-gated?

If this direction sounds acceptable, I'm happy to start with PR1 immediately (pure refactor) and keep everything else behind explicit opt-in settings.

[slkzgm]

FYI: PR1 (UI-only, no-op refactor to centralize event subscriptions) is up: #55
This is intended to be the first incremental step from the plan above and should not impact existing behavior.

[Dimillian]

So, merging #55 unlocks the rest for you?

Keeping that behind a setting is reasonable if it doesn't complicate/load the release proccess etc...

• Protocol: I feel like JSON-RPC is tidier
• I think app setting simplify things quite a bit, unless adding remote workspace is a use case
• No idea, whatever is best for you
• Need to see, deamon is fine if optional

[slkzgm]

Thanks for the feedback!

Yes — merging #55 is the first small step that unblocks the rest on my side: it centralizes event subscriptions so later we can swap the event source (today Tauri listen(...), later a remote transport) without having to refactor multiple hooks/components. It’s not implementing remote mode yet, but it reduces the churn surface for PR2/PR4.

Re: release process / complexity: totally agree. The remote backend would be strictly opt-in behind an app-level setting, with no default behavior change.

For the daemon specifically, I’d keep it optional (feature-gated and/or built only in a dedicated workflow / separate artifact) so it doesn’t complicate the default release.

Protocol: +1 on JSON-RPC. I’m planning JSON-RPC requests/responses + event notifications (so it stays close to the existing app-server mental model).

Config: app-level setting makes sense. Remote workspaces can remain managed on the backend side; no need for per-workspace remote config unless we discover a strong use case.

Paths / attachments: for an initial version, I’m fine with remote mode requiring remote filesystem paths (and disabling host file pickers), and keeping image/file attachments limited to paths accessible to the backend. Upload-bytes could be a later enhancement if needed.

If you’re OK with that direction, I’ll wait for #55 to land, then submit PR2 (backend refactor only, still no-op) before proposing anything daemon-related.

[Dimillian]

Sound good! I'll look at #55!

[Dimillian]

Merged!

[slkzgm]

Quick status update: I have a full working integration on my fork (branch wip/remote-backend) that demonstrates the end goal: native Windows UI (WebView2) + Codex runtime in WSL2/Linux via an opt-in remote backend daemon (local mode unchanged).

Tested on Win11 + WSL2: workspace add via \\wsl$\\<distro>\\home\\... / \\wsl.localhost\\<distro>\\home\\... (normalized to /home/...), workspace connect, threads list/start/resume, streaming, approvals, file listing, and Git panel (status/diffs/log/branches). (GitHub issues requires gh installed on the daemon machine.)

Fork/branch: https://github.com/slkzgm/CodexMonitor/tree/wip/remote-backend

Happy to record a short Loom/GIF demo if that helps review.

[slkzgm]

Quick status update: I've opened the next two incremental PRs (both target main, not stacked):

• feat(settings): add remote backend configuration #70 — app-level settings for selecting/configuring the remote backend (backendMode, remoteBackendHost, remoteBackendToken). Default behavior remains unchanged.
• feat(daemon): add workspace management RPC #71 — daemon-side workspace management JSON-RPC methods (list/add/connect/remove/update/list-files), plus forwarding CODEX_HOME when spawning worktree sessions. Default behavior remains unchanged.

Next (after merge of #70 / #71): I'll open the proxy/event-bridging PR, then the client workspace ops + WSL path normalization PR.

[slkzgm]

Status update:

• PR5 opened: feat(remote): proxy core commands via daemon #121 (remote backend proxy / command forwarding; still opt-in, default local unchanged)

Next (after #121): I’ll open PR6b (client workspace ops + WSL path normalization) as discussed.