Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

feat(host): ship the Linux screen helper with the host

leepokai37851fbdcc0c
diff --git a/.github/workflows/host.yml b/.github/workflows/host.yml
index 231f3968..8954cb51 100644
--- a/.github/workflows/host.yml
+++ b/.github/workflows/host.yml
@@ -35,7 +35,9 @@ jobs:
matrix:
include:
# musl: one static binary that runs on any distro, whatever its glibc.
- - { os: ubuntu-latest, target: x86_64-unknown-linux-musl, name: linux-x86_64 }
+ # codync-screen (Remote screen on Linux) links the system GStreamer 1.22+, so it is built
+ # for glibc on Ubuntu 24.04 and ships next to the host in the same archive.
+ - { os: ubuntu-24.04, target: x86_64-unknown-linux-musl, name: linux-x86_64 }
- { os: ubuntu-24.04-arm, target: aarch64-unknown-linux-musl, name: linux-arm64 }
- { os: macos-latest, target: aarch64-apple-darwin, name: macos-arm64 }
- { os: macos-latest, target: x86_64-apple-darwin, name: macos-x86_64 }
@@ -48,7 +50,9 @@ jobs:
run: rustup toolchain install
- run: rustup target add ${{ matrix.target }}
- if: runner.os == 'Linux'
- run: sudo apt-get update && sudo apt-get install -y musl-tools
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y musl-tools libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev
- name: Build
working-directory: host
# Vendored C (dbus) would call libgcc's outline atomics, which a static musl link lacks.
@@ -58,11 +62,15 @@ jobs:
VERSION=$(python3 -c 'import tomllib; print(tomllib.load(open("Cargo.toml", "rb"))["package"]["version"])')
test "v$VERSION" = "$GITHUB_REF_NAME" || { echo 'Host version must match release tag'; exit 1; }
cargo build --release --target ${{ matrix.target }}
+ - name: Build codync-screen
+ if: runner.os == 'Linux'
+ run: cargo build --release --manifest-path apps/screen-linux/Cargo.toml
- name: Package
run: |
NAME=codync-host-${{ matrix.name }}
mkdir $NAME
cp host/target/${{ matrix.target }}/release/codync-host $NAME/
+ if [ "$RUNNER_OS" = Linux ]; then cp apps/screen-linux/target/release/codync-screen $NAME/; fi
cp LICENSE $NAME/
tar czf $NAME.tar.gz $NAME
shasum -a 256 $NAME.tar.gz > $NAME.tar.gz.sha256
diff --git a/docs/features/remote-screen.md b/docs/features/remote-screen.md
index e512a9c3..df0991a5 100644
--- a/docs/features/remote-screen.md
+++ b/docs/features/remote-screen.md
@@ -31,7 +31,7 @@ computer display without choosing the phone's orientation.
- `host/src/screen.rs` coordinates access to the local helper and owns viewer sessions. Another device cannot renegotiate or close a session it does not own.
- `apps/screen-macos/` is the macOS capture/input helper (Xcode `Screen` target, `CodyncScreen.app`). The desktop app bundles it and registers it through `SMAppService` (`apps/desktop/src/main/screen.ts`); it is responsible for the OS permissions.
-- `apps/screen-linux/` implements the Linux helper using desktop portals and GStreamer, including ICE URL conversion and TURN transport configuration. The host starts it.
+- `apps/screen-linux/` implements the Linux helper using desktop portals and GStreamer, including ICE URL conversion and TURN transport configuration. The host starts it from beside its own executable (then `PATH`). Linux host releases ship `codync-screen` in the same archive (built on Ubuntu 24.04: glibc 2.39+ and GStreamer 1.22+ with the base, good and bad plugins, PipeWire and xdg-desktop-portal at run time); `install.sh`, Homebrew and `codync-host update` put it next to the host.
- Helpers communicate locally through `~/.codync/screen.sock`. SDP is non-trickle; input uses the `input` and `input-fast` data channels.
- Screen access is off by default. Enabling through `setScreenEnabled` requires a loopback caller. Interactive OS permission prompts must be completed on the computer.
- Bots with their computer capability enabled receive the built-in `computer` MCP tools (`host/src/mcp.rs`). Their permission policy still applies. An interactive phone can take over; bots may still look.
diff --git a/host/src/update/install.rs b/host/src/update/install.rs
index 8d37249d..8cad40e3 100644
--- a/host/src/update/install.rs
+++ b/host/src/update/install.rs
@@ -181,8 +181,10 @@ pub async fn apply(
}
let bytes = release::archive(release).await?;
let stage = target.with_file_name(format!(".codync-host-update-{}", uuid::Uuid::new_v4()));
+ let helper = Helper::new(target);
let result = async {
release::extract(&bytes, &release.platform, &stage)?;
+ let has_helper = release::extract_file(&bytes, &release.platform, HELPER, &helper.stage)?;
let output = tokio::process::Command::new(&stage).arg("--version").kill_on_drop(true).output();
let output = tokio::time::timeout(Duration::from_secs(10), output).await??;
ensure!(
@@ -213,6 +215,11 @@ pub async fn apply(
if managed {
tokio::task::spawn_blocking(service::stop).await??;
}
+ // Swapped while the host is stopped, so the new host never starts the old helper.
+ // A failed swap keeps the old helper rather than leaving the host stopped.
+ if has_helper && let Err(error) = helper.swap() {
+ tracing::warn!(error = format!("{error:#}"), "screen helper not updated");
+ }
Ok(())
},
|| async {
@@ -223,6 +230,7 @@ pub async fn apply(
Ok(())
},
|| async {
+ helper.restore();
if managed {
tokio::task::spawn_blocking(service::stop).await??;
tokio::task::spawn_blocking(service::start).await??;
@@ -236,5 +244,56 @@ pub async fn apply(
}
.await;
let _ = std::fs::remove_file(stage);
+ helper.finish();
result
}
+
+/// The Linux Remote screen helper ships in the host's archive; the host starts it from beside
+/// itself, so an update replaces it there too.
+const HELPER: &str = "codync-screen";
+
+/// Swaps the helper beside the host for the staged one, keeping a copy to roll back to.
+struct Helper {
+ path: std::path::PathBuf,
+ stage: std::path::PathBuf,
+ backup: std::path::PathBuf,
+ swapped: std::sync::atomic::AtomicBool,
+}
+
+impl Helper {
+ fn new(target: &Path) -> Self {
+ let id = uuid::Uuid::new_v4();
+ Self {
+ path: target.with_file_name(HELPER),
+ stage: target.with_file_name(format!(".{HELPER}-update-{id}")),
+ backup: target.with_file_name(format!(".{HELPER}-backup-{id}")),
+ swapped: std::sync::atomic::AtomicBool::new(false),
+ }
+ }
+
+ fn swap(&self) -> Result<()> {
+ if self.path.exists() {
+ std::fs::hard_link(&self.path, &self.backup).context("saving the screen helper")?;
+ }
+ std::fs::rename(&self.stage, &self.path).context("replacing the screen helper")?;
+ self.swapped.store(true, std::sync::atomic::Ordering::Relaxed);
+ Ok(())
+ }
+
+ /// Puts the previous helper back (or removes a new one that had none before).
+ fn restore(&self) {
+ if !self.swapped.load(std::sync::atomic::Ordering::Relaxed) {
+ return;
+ }
+ if self.backup.exists() {
+ let _ = std::fs::rename(&self.backup, &self.path);
+ } else {
+ let _ = std::fs::remove_file(&self.path);
+ }
+ }
+
+ fn finish(&self) {
+ let _ = std::fs::remove_file(&self.stage);
+ let _ = std::fs::remove_file(&self.backup);
+ }
+}
diff --git a/host/src/update/release.rs b/host/src/update/release.rs
index 93bfac23..b8d22a95 100644
--- a/host/src/update/release.rs
+++ b/host/src/update/release.rs
@@ -139,10 +139,20 @@ pub async fn archive(release: &Release) -> Result<Vec<u8>> {
/// Extract just the expected regular executable. Never unpack archive paths,
/// symlinks, permissions or other files into the user's installation.
pub fn extract(bytes: &[u8], platform: &str, destination: &Path) -> Result<()> {
+ ensure!(
+ extract_file(bytes, platform, "codync-host", destination)?,
+ "release archive does not contain its host executable"
+ );
+ Ok(())
+}
+
+/// Extracts one executable shipped beside the host (`codync-screen` on Linux), with the same
+/// rules as [`extract`]. `false` when the archive doesn't carry it.
+pub fn extract_file(bytes: &[u8], platform: &str, name: &str, destination: &Path) -> Result<bool> {
use std::os::unix::fs::PermissionsExt as _;
let decoder = flate2::read::GzDecoder::new(bytes).take(MAX_UNPACKED);
let mut archive = tar::Archive::new(decoder);
- let expected = format!("codync-host-{platform}/codync-host");
+ let expected = format!("codync-host-{platform}/{name}");
let mut found = false;
for entry in archive.entries()? {
let mut entry = entry?;
@@ -157,6 +167,5 @@ pub fn extract(bytes: &[u8], platform: &str, destination: &Path) -> Result<()> {
file.sync_all()?;
found = true;
}
- ensure!(found, "release archive does not contain its host executable");
- Ok(())
+ Ok(found)
}
diff --git a/host/src/update/tests.rs b/host/src/update/tests.rs
index 89d8e9db..33ccfd13 100644
--- a/host/src/update/tests.rs
+++ b/host/src/update/tests.rs
@@ -99,6 +99,25 @@ fn extraction_refuses_symlinks_and_only_creates_the_expected_binary() {
assert!(release::extract(&archive(false), "linux-arm64", &target).is_err());
}
+#[test]
+fn the_screen_helper_is_extracted_only_when_the_archive_carries_it() {
+ let dir = Directory::new();
+ let gzip = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
+ let mut tar = tar::Builder::new(gzip);
+ for (name, contents) in [("codync-host", b"new"), ("codync-screen", b"scr")] {
+ let mut header = tar::Header::new_gnu();
+ header.set_mode(0o755);
+ header.set_size(3);
+ header.set_cksum();
+ tar.append_data(&mut header, format!("codync-host-linux-arm64/{name}"), &contents[..]).unwrap();
+ }
+ let with_helper = tar.into_inner().unwrap().finish().unwrap();
+ let helper = dir.0.join("helper");
+ assert!(release::extract_file(&with_helper, "linux-arm64", "codync-screen", &helper).unwrap());
+ assert_eq!(std::fs::read(&helper).unwrap(), b"scr");
+ assert!(!release::extract_file(&archive(false), "linux-arm64", "codync-screen", &dir.0.join("none")).unwrap());
+}
+
#[tokio::test]
async fn a_failed_health_check_restores_the_previous_binary_and_service() {
let dir = Directory::new();
diff --git a/packaging/homebrew/codync-host.rb b/packaging/homebrew/codync-host.rb
index 9e7b4093..76c30208 100644
--- a/packaging/homebrew/codync-host.rb
+++ b/packaging/homebrew/codync-host.rb
@@ -33,6 +33,8 @@ class CodyncHost < Formula
def install
bin.install "codync-host"
+ # Linux: the Remote screen helper (needs the system's GStreamer and xdg-desktop-portal).
+ bin.install "codync-screen" if OS.linux?
end
def caveats
diff --git a/packaging/install.sh b/packaging/install.sh
index 0cc971d3..a1ebc79b 100755
--- a/packaging/install.sh
+++ b/packaging/install.sh
@@ -65,6 +65,8 @@ install_host() {
fetch "$name.tar.gz"
tar xzf "$TMP/$name.tar.gz" -C "$TMP"
place "$TMP/$name/codync-host" "$BIN_DIR/codync-host"
+ # Linux: the Remote screen helper, which the host starts from beside itself.
+ if [ -f "$TMP/$name/codync-screen" ]; then place "$TMP/$name/codync-screen" "$BIN_DIR/codync-screen"; fi
say "Installed $("$BIN_DIR/codync-host" --version) to $BIN_DIR"
restart_service "$BIN_DIR/codync-host"
}