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.

fix(host): keep remote screen off on headless linux

leepokaib42b6a923f45
diff --git a/CLAUDE.md b/CLAUDE.md
index 1807b7f5..c016cad3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ Bot-based remote for coding agents: persistent named bots on your computer, mess
- **Sync**: every mutation stamps a global `rev`. Clients call `GET /events?since=<rev>` (catch-up in rev order, then live). Emission happens under `Hub::emit_lock` so events leave in rev order. Clients upsert by id; never skip undecodable events (the iOS app rewinds to rev 0).
- API: `POST /api/<method>` + SSE with the bearer token (`~/.codync/token`) is **loopback only** (desktop app, SSH tunnel, local helpers). Phones and other remote clients use the E2E channel (`/channel` direct, or the Cloudflare relay). Default port **19222**.
- Remote access (Cloudflare relay primary, direct LAN/Tailscale alternative, accounts, SSH, public routine webhooks queued in the relay §7.8): [docs/reference/remote-relay.md](docs/reference/remote-relay.md).
-- Remote screen (`host/src/screen.rs` is the reference): phones view/control the computer over WebRTC (hardware H.264, non-trickle SDP relayed by `screenOffer`, input on data channels `input` / `input-fast`); bots get the built-in `computer` MCP server (`codync-host mcp computer`, `host/src/mcp.rs`) when their `computer` flag is on. Capture/input live in a helper on `~/.codync/screen.sock`: `apps/screen-macos` (macOS, launchd agent the desktop app registers via `SMAppService`, owns the TCC grants) or `apps/screen-linux` (`codync-screen`: portals + GStreamer, started by the host). On by default; `setScreenEnabled` is accepted only from loopback. An interactive phone takes over (bots may only look).
+- Remote screen (`host/src/screen.rs` is the reference): phones view/control the computer over WebRTC (hardware H.264, non-trickle SDP relayed by `screenOffer`, input on data channels `input` / `input-fast`); bots get the built-in `computer` MCP server (`codync-host mcp computer`, `host/src/mcp.rs`) when their `computer` flag is on. Capture/input live in a helper on `~/.codync/screen.sock`: `apps/screen-macos` (macOS, launchd agent the desktop app registers via `SMAppService`, owns the TCC grants) or `apps/screen-linux` (`codync-screen`: portals + GStreamer, started by the host). On by default (Linux: only with a graphical session); `setScreenEnabled` is accepted only from loopback. An interactive phone takes over (bots may only look).
- Multiple computers per account are future work, not a current priority: the product targets one computer. The multi-computer structure (`AccountStore`, `BotReference`) stays because relay/accounts/SSH build on it; don't extend or polish multi-computer features unless asked.
- Environments: **dev** (`dev-api.codync.dev`, Clerk development instance, Debug builds) and **main** (`api.codync.dev`, Clerk production, Release builds); `apps/shared/Config/<env>.plist` becomes the iOS `AccountConfig.plist` and the desktop `resources/account-config.json` (`tools/account-config.mjs`). Details: [spec §14.0](docs/reference/remote-relay.md).
- Push: iOS registers its APNs token with `relay/` → gets an AES-GCM ticket → gives it (plus its X25519 push key) to the host; the host seals title/body to that key and a Notification Service Extension opens it, so `relay/` sees only generic text. Alert kinds: *needs you*, *done*, and *failed*, suppressed while the iOS app is connected. Delivery and lifecycle: [notification design](docs/design/push-and-live-activity.md).
diff --git a/docs/features/remote-screen.md b/docs/features/remote-screen.md
index 482cac34..30fd1fd5 100644
--- a/docs/features/remote-screen.md
+++ b/docs/features/remote-screen.md
@@ -33,7 +33,7 @@ computer display without choosing the phone's orientation.
- `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 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 on by default (turning it off is remembered). Enabling through `setScreenEnabled` requires a loopback caller. Interactive OS permission prompts must be completed on the computer.
+- Screen access is on by default on macOS and on Linux while a graphical session (Wayland or X11) is running; headless servers stay off. Turning it on or off is remembered. 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.
- Each device may hold four sessions; the host allows 32 total, including pending sessions. Credential issuance is limited to 12 requests per minute per account by `TURN_LIMITER` (Cloudflare's per-location rate limiter).
- Closing a session stops its media; issued TURN credentials remain usable until their one-hour TTL. Issuance limits and encoder limits do not constitute a hard monthly spending cap. Track Realtime egress by the credential's custom identifier.
diff --git a/docs/guides/linux-servers.md b/docs/guides/linux-servers.md
index 14e81bbd..a63416d4 100644
--- a/docs/guides/linux-servers.md
+++ b/docs/guides/linux-servers.md
@@ -42,7 +42,7 @@ The host listens on `0.0.0.0:19222`. The local API (`/api/*`, `/events`, termina
## Limitations on a headless server
-- **Remote screen and the `computer` tool don't work.** They need a desktop session (portals + GStreamer, `apps/screen-linux/`). Without one, the host keeps retrying the helper in the background; nothing else is affected.
+- **Remote screen and the `computer` tool don't work.** They need a desktop session (portals + GStreamer, `apps/screen-linux/`). The feature turns itself on only while a graphical session is running, so on a server it stays off and nothing else is affected.
- **No desktop app.** The Linux desktop app (`codync`, AppImage/deb/tar.gz) needs a graphical session; it uses the installed `codync-host`. On a server, use the phone, the desktop app on another computer over SSH, or `codync-host tui`.
- **Keep-awake is a no-op.** The host tries `systemd-inhibit` while a bot works; VMs don't sleep, and failure only logs a warning.
- **One computer per account.** A VM counts as the account's computer; multiple computers are future work.
diff --git a/host/src/screen.rs b/host/src/screen.rs
index aa7e5e23..b58c3629 100644
--- a/host/src/screen.rs
+++ b/host/src/screen.rs
@@ -5,8 +5,8 @@
//! that connects to `~/.codync/screen.sock` — on macOS `CodyncScreen.app`
//! (a signed bundle, so Screen Recording / Accessibility grants stick), on
//! Linux `codync-screen` (xdg portals + `GStreamer`). The host stays the only
-//! network-facing process: it relays WebRTC signaling, gates access (off by
-//! default, enabled only from this computer) and arbitrates control between
+//! network-facing process: it relays WebRTC signaling, gates access (on by
+//! default where there is a desktop, toggled only from this computer) and arbitrates control between
//! the user and bots.
//!
//! Helper protocol: newline-delimited JSON-RPC 2.0 over the socket.
@@ -37,7 +37,7 @@ use serde_json::{Value, json};
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::Mutex;
-use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicI64, AtomicU64, Ordering};
use std::time::{Duration, Instant};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::net::{UnixListener, UnixStream};
@@ -386,7 +386,8 @@ struct Viewer {
}
pub struct Screen {
- enabled: AtomicBool,
+ /// The user's choice; `None` until they make one (see [`Screen::enabled`]).
+ enabled: Mutex<Option<bool>>,
events: broadcast::Sender<Value>,
link: Mutex<Option<Arc<Link>>>,
status: Mutex<HelperStatus>,
@@ -396,9 +397,9 @@ pub struct Screen {
}
impl Screen {
- pub fn new(enabled: bool, events: broadcast::Sender<Value>) -> Self {
+ pub fn new(enabled: Option<bool>, events: broadcast::Sender<Value>) -> Self {
Self {
- enabled: AtomicBool::new(enabled),
+ enabled: Mutex::new(enabled),
events,
link: Mutex::default(),
status: Mutex::default(),
@@ -408,12 +409,19 @@ impl Screen {
}
}
- pub fn load_enabled(store: &crate::store::Store) -> bool {
- store.kv_get(KV_ENABLED).as_deref() != Some("0")
+ pub fn load_enabled(store: &crate::store::Store) -> Option<bool> {
+ match store.kv_get(KV_ENABLED).as_deref() {
+ Some("1") => Some(true),
+ Some("0") => Some(false),
+ _ => None,
+ }
}
+ /// On by default wherever there is a screen to share: always on macOS, and on Linux
+ /// only while a graphical session is up (checked live, so a headless server stays off
+ /// and a desktop that logs in after the host started turns on).
pub fn enabled(&self) -> bool {
- self.enabled.load(Ordering::Relaxed)
+ (*self.enabled.locked()).unwrap_or_else(graphical_session)
}
/// What clients show: availability, permissions, displays, who's in control.
@@ -572,7 +580,7 @@ impl Screen {
/// Only callable from this computer (see `api/mod.rs`).
pub async fn set_enabled(&self, store: &crate::store::Store, on: bool) -> Result<()> {
store.kv_set(KV_ENABLED, if on { "1" } else { "0" })?;
- self.enabled.store(on, Ordering::Relaxed);
+ *self.enabled.locked() = Some(on);
if !on {
let link = self.link.locked().clone();
if let Some(link) = link
@@ -801,6 +809,22 @@ pub async fn serve_helpers(screen: Arc<Screen>) {
}
}
+#[cfg(target_os = "macos")]
+fn graphical_session() -> bool {
+ true
+}
+
+/// A Wayland socket in this user's runtime dir, or a running X server.
+#[cfg(not(target_os = "macos"))]
+fn graphical_session() -> bool {
+ let has = |dir: &std::path::Path, prefix: &str| {
+ std::fs::read_dir(dir)
+ .is_ok_and(|entries| entries.flatten().any(|e| e.file_name().to_string_lossy().starts_with(prefix)))
+ };
+ std::env::var_os("XDG_RUNTIME_DIR").is_some_and(|dir| has(dir.as_ref(), "wayland-"))
+ || has(std::path::Path::new("/tmp/.X11-unix"), "X")
+}
+
/// Linux: the host runs `codync-screen` itself while Remote screen is on (on macOS
/// launchd runs Codync Screen for the app). Restarts it if it exits; stops it when turned off.
#[cfg(target_os = "linux")]
@@ -956,7 +980,7 @@ mod tests {
#[test]
fn user_takeover_blocks_bot_actions_but_not_looking() {
let (tx, _) = broadcast::channel(8);
- let s = Screen::new(true, tx);
+ let s = Screen::new(Some(true), tx);
assert!(s.claim("a", false).unwrap());
assert!(!s.claim("a", false).unwrap());
assert!(s.claim("b", true).is_err(), "one bot at a time");
@@ -976,7 +1000,7 @@ mod tests {
#[test]
fn prepared_sessions_are_bounded_and_do_not_count_as_viewers() {
let (tx, _) = broadcast::channel(8);
- let screen = Screen::new(true, tx);
+ let screen = Screen::new(Some(true), tx);
let (tx, _) = mpsc::unbounded_channel();
*screen.link.locked() =
Some(Arc::new(Link { id: 1, tx, pending: Mutex::default(), next_id: AtomicI64::new(1) }));
@@ -1003,14 +1027,14 @@ mod tests {
viewer.pending_until = 0;
}
assert!(screen.prepare("phone", IceConfig::default()).is_ok());
- screen.enabled.store(false, Ordering::Relaxed);
+ *screen.enabled.locked() = Some(false);
assert!(screen.prepare("phone", IceConfig::default()).is_err());
}
#[tokio::test]
async fn helper_roundtrip_over_the_socket() {
let (tx, _) = broadcast::channel(8);
- let screen = Arc::new(Screen::new(true, tx));
+ let screen = Arc::new(Screen::new(Some(true), tx));
let (a, b) = UnixStream::pair().unwrap();
let (observed_tx, mut observed_rx) = mpsc::unbounded_channel();
// Fake helper reports a display and records the host's ICE configuration.