Skip to content

feat(remote-control): self-hosted remote control server and web/mobile app - #7

Merged
synthet merged 9 commits into
masterfrom
ccr-70476bc9-l4iey6
Nov 5, 2026
Merged

synthet merged 9 commits into
masterfrom
ccr-70476bc9-l4iey6

Conversation

@synthet

@synthet synthet commented Oct 17, 2026

Copy link
Copy Markdown
Owner

Description

Lets you remote-control every terminal from a browser or phone through a server you run yourself, with no Warp account. Warp's hosted sharing server and web viewer are closed and paid, but the protocol (session-sharing-protocol) and the client-side sharing code are already in this repo. So this PR adds a server that speaks that protocol, plus a few client switches.

New: crates/remote_control_server (synth-remote-control-server binary)

  • Accepts shared terminals and keeps their output, so a viewer who joins late sees the full scrollback.
  • Checks permissions on remote input and drops sessions whose terminal stays offline too long.
  • Access uses one shared token. Requests from other origins are refused.
  • Serves a built-in web/mobile app:
    • a dashboard of every shared terminal across machines (host, folder, whether something is running);
    • a terminal view where you run commands at the prompt or type into a running program;
    • a phone key bar (Esc, Tab, ^C, ^D, arrows, Enter) and resize-to-fit when the phone is the only viewer;
    • installable as a home-screen app. xterm.js is bundled (MIT), so nothing loads from a CDN.

Client

  • SYNTH_WARP_REMOTE_CONTROL_URL and SYNTH_WARP_REMOTE_CONTROL_TOKEN enable sharing to that server with no Warp login and no Warp permissions dialog. warp.dev addresses are refused.
  • SYNTH_WARP_REMOTE_CONTROL_ALL_TERMINALS=1 shares every terminal when it starts. In that mode the link isn't copied to the clipboard, closing a tab doesn't ask for confirmation, and a rejected resume (server restarted or session reaped) starts a fresh share instead of showing an error.
  • Desktop idleness no longer revokes remote control. Upstream revokes it after 10 minutes.

Docs: spec in specs/self-hosted-remote-control/, setup guide in docs/guides/self-hosted-remote-control.md, and an FAQ entry.

Known limitations

  • Setup is by environment variables only; there's no settings page.
  • The client stops sharing a terminal after 100 MB of output, and it has to be shared again.
  • Warp's own prompt doesn't show in the browser, because the web app renders raw PTY output.
  • Sessions are kept in memory only (auto-share covers server restarts).
  • Plain ws:// is only for a trusted LAN or Tailscale. Anywhere else, put it behind HTTPS; the guide has a Caddy example.

Linked Issue

There's no tracking issue; this was requested directly in a session. The spec is in specs/self-hosted-remote-control/.

  • The linked issue is labeled ready-to-spec or ready-to-implement.
  • Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes).

Testing

  • remote_control_server: 18 unit tests and 2 tests over real WebSocket connections pass.

  • cargo clippy -D warnings and rustfmt are clean for remote_control_server, warp_core and warp (lib and warp-oss bin).

  • End to end with a real warp-oss build under Xvfb and auto-share on:

    • each new tab shared itself with no login and appeared on the dashboard;
    • from Chromium at phone size I ran a command, typed into a running cat, and stopped it with ^C, and all of it showed on the desktop;
    • after a server restart, the terminal shared itself again.
  • That run caught a real bug: the client sends PTY output as LZ4 blocks with a size prefix, so the web view first showed garbage. The fix decodes it and was checked against frames captured from the real app.

  • The warp lib test binary was killed for lack of memory in the 15 GB build container. I ran the two new self_hosted tests word for word in a separate small crate instead, and both pass. CI should run them in place.

  • I have manually tested my changes locally with ./script/run. (Tested with warp-oss under Xvfb in a cloud container, not ./script/run on a desktop.)

Agent Mode

  • Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-NEW-FEATURE: Remote-control your terminals from a browser or phone through a self-hosted server, with no Warp account.


Generated by Claude Code

…e app

Replace Warp's hosted (paid) session-sharing / "Remote control" service
with a server users run themselves.

- crates/remote_control_server: `synth-remote-control-server`, an axum
  implementation of the public session-sharing-protocol (create, resume,
  join, event log replay, role-checked viewer input, size caps, reaping)
  with shared-token auth and same-origin websocket checks.
- Embedded PWA: dashboard of every shared terminal across machines, and
  an xterm.js remote that runs commands at an idle prompt and types into
  running programs (CLI agents), with a mobile key bar and viewer-driven
  PTY sizing. xterm.js 5.5.0 + fit addon vendored (MIT).
- Client: SYNTH_WARP_REMOTE_CONTROL_URL / _TOKEN re-enable sharing on OSS
  builds without a Warp login or ACL dialog; Warp hosts are refused.
  SYNTH_WARP_REMOTE_CONTROL_ALL_TERMINALS=1 shares every terminal on its
  first bootstrap without clobbering the clipboard or confirming closes.
  Self-hosted shares skip the local-inactivity revoke/end timer.
- Spec, operator guide, FAQ and fork docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RjzGqX8oGNquhmAvzCNjxR
…restart

- The web app wrote PtyBytesRead payloads verbatim, but sharers send each
  batch as an LZ4 block with a prepended size, so the browser showed
  garbage. Decode it (verified against frames from a real warp-oss).
- In share-all mode, a rejected resume (server restarted or session
  reaped) now starts a fresh share instead of an error toast, so
  terminals return to the dashboard on their own.

Verified end to end: warp-oss under Xvfb auto-shares each new tab with
no Warp login; the web app runs a command, types into a running program,
sends ^C; a server restart re-shares the terminal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RjzGqX8oGNquhmAvzCNjxR
Run ./script/format, which groups imports by module
(imports_granularity=Module, group_imports=StdExternalCrate). Plain
rustfmt left them split, failing the "Formatting + Clippy" CI check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RjzGqX8oGNquhmAvzCNjxR

synthet commented Oct 17, 2026

Copy link
Copy Markdown
Owner Author

CI status for the first run (0152c3b). This is the first Warp CI run on this fork that executed jobs; every earlier run was skipped. So several failures are pre-existing on master and would hit any PR.

This PR's failure, fixed in 7b7870e

  • Formatting + Clippy (Linux): import grouping didn't match ./script/format. Fixed by running ./script/format. Locally, ./script/format --check, cargo clippy -D warnings (remote_control_server and warp_core with --all-targets, warp lib + tests) and cargo deny check licenses all pass.

Not caused by this PR (none of the failing code is in this diff; no fix exists yet)

  • Formatting + Clippy (MacOS), Verify compilation (MacOS): the runner has no Xcode 26 (Could not find Xcode version that satisfied version spec: '26'). Fix: pin xcode-version in ci.yml to an installed version, or move to a runner image that has 26.
  • Run MacOS tests: protoc is missing on the runner (warp_multi_agent_api build script). It needs the same install step the other macOS jobs use.
  • Formatting + Clippy (wasm): unused import parse_current_url, update_browser_url at app/src/workspace/view.rs:447, behind #[cfg(target_family = "wasm")]. It's on master already; this PR's hunks in that file don't touch it. Fix: delete those two lines.
  • Miscellaneous checks: PSScriptAnalyzer reports 13 warning-level findings in the fork's build.ps1 / deploy.ps1. Once that step passes, script/check_no_inline_test_modules will also flag crates/warp_core/src/channel/config.rs:217.
  • Run Linux tests: 11,698 of 11,703 unit tests passed, including this PR's. The 5 failures are all in warp_tui (handoff_tests ×4, orchestration_model::tests::remote_dispatch_uses_captured_scope_and_auth_secret), a crate this PR doesn't touch. The job then timed out during the GUI integration tests.

I'll put these to the repo owner as a separate CI-fix PR rather than widen this one.


Generated by Claude Code

synthet commented Oct 17, 2026

Copy link
Copy Markdown
Owner Author

Update for 7b7870e: Formatting + Clippy (Linux) now passes the format check. Clippy then failed, but not on this PR's code.

Clippy fails on 3 dead_code errors in app/src/tui/, a directory this PR doesn't touch:

  • set_logged_out_phase (app/src/tui/mod.rs:389)
  • Journey::PostLogout (app/src/tui/telemetry.rs:27)
  • post_logout_authentication_started (app/src/tui/telemetry.rs:386)

All three are called only from mod_tests.rs / telemetry_tests.rs. So warp's lib flags them whenever the tui feature is on, and CI turns that feature on through workspace feature unification. master fails the same way.

I reproduced it locally with cargo clippy -p warp --lib --features tui -- -D warnings on this branch. Those 3 errors are the only ones, so this PR's code is clean under the tui feature as well.

No fix exists yet. The proposed fix is to call set_logged_out_phase from the TUI logout path it was written for, or to put the three items behind #[cfg(test)]. That would also need the Journey::PostLogout match arm at telemetry.rs:346 gated. I'll leave this to a separate CI-fix PR, like the other failures listed above.


Generated by Claude Code

synthet commented Oct 18, 2026

Copy link
Copy Markdown
Owner Author

On 9f51e48, Formatting + Clippy (MacOS) and Verify compilation with release flags (MacOS) still fail, but one step later than before. Xcode 16 now installs, and then "Install dependencies" exits 64: xcodebuild prints its usage text because it doesn't recognize an option.

The command is xcodebuild -downloadComponent MetalToolchain in script/macos/install_build_deps. That option only exists in Xcode 26; Xcode 16 ships the Metal toolchain built in. The fork's GitHub-hosted runner is macos-14 (ci.yml:77), and its newest Xcode is 16.2. So on that image the job fails with either Xcode pin.

Two ways out:

  1. Move to a runner image that has Xcode 26 (my recommendation, closest to upstream): set RUNNER_TYPE='["macos-26"]' at ci.yml:77 and put xcode-version: '26' back.
  2. Stay on macos-14 / Xcode 16: skip the download when it isn't supported, e.g. xcodebuild -downloadComponent MetalToolchain 2>/dev/null || true. Risk: anything that needs the macOS 26 SDK will then fail at compile time.

This is CI configuration you're actively changing on this branch, so I haven't pushed either one.


Generated by Claude Code

@synthet

synthet commented Oct 18, 2026

Copy link
Copy Markdown
Owner Author

Reopening to trigger fresh CI run

@synthet synthet closed this Oct 18, 2026
@synthet synthet reopened this Oct 18, 2026
# Conflicts:
#	app/src/terminal/shared_session/sharer/network.rs
#	docs/log.md

synthet commented Oct 25, 2026

Copy link
Copy Markdown
Owner Author

CI status on head 3c0648e: the re-run of the failed jobs in run 39172797008 has been queued since 2026-10-23 22:02 UTC with no runner assigned. Not one job has started, so there is no new test result.

On the first attempt, Formatting + Clippy (Linux and wasm), Misc checks, the Linux, Windows and wasm release builds, and eval features all passed. "Run Linux tests" was killed by a runner shutdown signal while it was still compiling. The macOS and Windows jobs were cancelled.

A queue that sits this long is usually an Actions-side limit, not this PR. Things to check:

  • Actions minutes or spending limit (macOS minutes count 10×).
  • The availability of the runner labels in ci.yml.

I'm not re-running it again; my one re-run is spent. Once a runner picks it up, I'll fix any failure that comes from this PR's code.


Generated by Claude Code

@synthet
synthet merged commit 3c0648e into master Nov 5, 2026
10 of 17 checks passed
@synthet
synthet deleted the ccr-70476bc9-l4iey6 branch November 5, 2026 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants