GravityDesk

Self-Hosted Remote Control System for Google Antigravity (agy) CLI & Developer Workstations (Windows, macOS, Linux) over Tailscale

Control, prompt, and monitor autonomous Google Antigravity AI coding sessions on your developer workstation (Windows, macOS, or Linux) straight from your Android phone — wherever you are, zero cloud intermediaries required.

---

🌟 Highlights

• 🖥️ Modern Desktop GUI Control Center: Clean dark-mode Tkinter management window showing host status, detected Tailscale IPv4, dynamic high-resolution QR pairing code, 1-click token copy, workspace picker, and real-time activity log.
• ⚡ Zero-Lag Dual-Engine Virtual Terminal: Cross-platform pseudo-terminal streaming (Windows ConPTY & Unix POSIX PTY) directly over WebSocket with a 3,000-chunk ring buffer for lossless session catch-up.
• 🧠 Google Antigravity (agy) First-Class Citizen: Autonomous session continuity with --dangerously-skip-permissions, mobile-responsive ASCII welcome banner, and real-time conversation resume synchronized directly with local Antigravity SQLite storage.
• 📊 Live Antigravity Engine & Quota Telemetry: Real-time active model detection (settings.json, e.g., Gemini 3.8 Flash (High)), 5-hour session quota, and weekly quota limits with exact reset countdowns (Resets in 123h 29m), cached with zero CPU overhead and refreshable on-demand.
• 🪟 Zero-Popup Headless Background Execution: All background subprocesses (including agy -p /usage and audio transcoding) run silently without intrusive popup windows on the developer workstation.
• 🛡️ Subprocess Concurrency Guard: Single-flight prompt lock in SessionHub blocks overlapping execution requests and prevents runaway background tasks.
• 🎙️ Remote Voice-to-Text Dictation Pipeline: Native voice prompt bar with automated ffmpeg audio normalization to 16kHz PCM WAV and Google Speech Recognition fallback for hands-free agent steering.
• 📱 Native Android Companion App: Auto-expanding WhatsApp-style multiline prompt input, 1:1 mathematically aligned screen headers, quick signals (Ctrl+C), and live workstation vitals (CPU %, RAM %, Battery %, Charging status).
• 🧭 Multi-Drive Breadcrumb Workspace Navigator: Explore and switch project folders effortlessly across filesystem roots (C:\, D:\ on Windows, / and /Volumes on macOS/Linux) right from mobile.
• 🚫 Instant Access Revocation: One-click 256-bit cryptographic token rotation instantly locks out stale or lost mobile sessions and invalidates active connections in real time.
• 🔒 Zero-Trust Defense-in-Depth: Operates exclusively over encrypted Tailscale WireGuard mesh tunnels, timing-safe authentication (hmac.compare_digest), path-traversal safeguards, and strict command execution allowlists.
• 🔋 Power Management & Sleep Inhibit: Prevents host laptops from entering standby or suspend mode during active remote sessions.

---

📸 Interface Preview

🖥️ Desktop Host Control Center

Modern dark-mode dashboard with dynamic QR pairing, hardware vitals, active session management, and instant access revocation.

📱 Android Companion App

Control autonomous agent sessions, monitor Gemini quota limits, switch workspaces, and steer execution with voice or touch.

Mobile Dashboard & Engine Telemetry	Interactive Terminal & Voice Prompting
Real-time host vitals & Gemini/Claude quota tracking	Zero-lag virtual terminal, breadcrumb nav & voice STT

---

🛠️ Tech Stack

Layer	Technologies
Host Workstation	Windows 10 / 11, macOS, Linux, Python 3.12+, Tkinter, Pillow, ffmpeg
Backend Daemon	FastAPI, Uvicorn, pywinpty (Windows) / pty (Unix), psutil, qrcode, SpeechRecognition, SQLite
Networking	Tailscale (WireGuard Mesh), WebSocket (/ws/terminal), HTTP REST
Mobile Native	React Native, Expo, TypeScript, expo-secure-store, expo-av, lucide-react-native
Target Engine	Google Antigravity CLI (agy), Gemini / Claude / GPT models

---

🚀 Quick Start

1. Prerequisites

• Developer Workstation: Windows 10/11, macOS, or Linux.
• Python: Version 3.12+ installed and added to PATH.
• Google Antigravity: agy CLI installed globally and authenticated.
• Tailscale: Installed and signed in on both your host workstation and your Android phone on the same tailnet.
• FFmpeg (Optional): Required only if you want remote voice-to-text dictation. Typing prompts, running terminal commands, and telemetry work 100% without it.

2. Installation

Option A: Install via Git (Recommended for Users)

Install directly into your Python environment with automatic dependency resolution and global command registration:

# Direct pip install
pip install git+https://github.com/w1th0ut/GravityDesk.git

# Or via pipx (recommended for isolated environments on macOS / Linux)
pipx install git+https://github.com/w1th0ut/GravityDesk.git

Option B: Clone for Development

git clone https://github.com/w1th0ut/GravityDesk.git
cd GravityDesk
pip install -e .

(Optional) Enable Voice Dictation with FFmpeg

If you want to use the hands-free voice-to-text dictation feature from your Android phone, install FFmpeg on your host workstation:

# Windows (WinGet)
winget install Gyan.FFmpeg

# macOS (Homebrew)
brew install ffmpeg

# Linux (Ubuntu / Debian)
sudo apt update && sudo apt install -y ffmpeg

Note

FFmpeg is completely optional. GravityDesk operates normally without it; you will only receive an in-app notice on Android if you attempt to record a voice prompt without FFmpeg installed on the host.

3. Launching GravityDesk

Once installed, you can launch GravityDesk from any terminal window and from any directory on your workstation:

# Option A: Desktop GUI Control Center
gravitydesk

# Option B: Headless / CLI Daemon Mode (Linux VPS, headless server, or SSH)
gravitydesk --headless

# Option C: Update GravityDesk to the latest version
gravitydesk update

(If running directly from the cloned repository source without pip installation, python app.py and python app.py --headless continue to work identically).

The GravityDesk host will launch:

1. Automatically resolves your workstation's Tailscale IPv4 address.
2. Loads (or generates) your persistent 256-bit cryptographic auth token in ~/.gravitydesk/.env.
3. Renders a high-contrast QR Code directly in the GUI (or prints terminal QR in headless mode).
4. Starts the background FastAPI server on port 8000.

4. Installing & Pairing the Mobile App

1. Download Android App: Grab the latest gravitydesk-vx.x.x.apk directly from GitHub Releases and install it on your Android phone.
2. Connect Tailscale: Ensure both your host workstation and your Android phone are signed into the same Tailscale network.
3. Pair Instantly:
   • Launch GravityDesk on your phone.
   • Tap Scan QR and scan the MOBILE PAIRING QR code displayed in your Desktop GUI or terminal.
   • You are connected instantly with sub-50ms latency over your private WireGuard mesh tunnel!

5. Updating GravityDesk

Keep your GravityDesk host up to date with the latest features, security patches, and engine optimizations with a single command:

gravitydesk update

• If installed via Git / pip: Automatically fetches and upgrades to the latest release directly from GitHub without needing to remember repository URLs.
• If cloned locally: Automatically pulls the latest commits via git pull and refreshes your editable installation and dependencies (pip install -e .).

---

🔒 Security Architecture

GravityDesk is engineered with institutional-grade security principles for remote execution:

• Private WireGuard Mesh: The server binds exclusively within your private Tailscale network (100.x.y.z). No ports are forwarded to the public internet, completely eliminating external attack surfaces.
• Cryptographic Token Handshake: Authentication requires a 256-bit token generated via Python's secrets.token_hex(32). Requests are validated using constant-time comparison (hmac.compare_digest) to protect against side-channel timing attacks.
• Instant Revocation: Compromised your phone or lost access? Tap 🚫 Reset Pairing Token in the Desktop GUI. GravityDesk generates a new 256-bit secret, overwrites .env, and invalidates all existing sessions immediately.
• Binary Allowlist: Spawning arbitrary executables is prohibited. Only pre-vetted shells (bash, zsh, sh, cmd.exe, powershell.exe) and Google Antigravity (agy, agy.exe) are permitted.
• Path Traversal Protection: Folder browsing requests are sanitized via os.path.realpath, validating paths against filesystem roots (C:\, D:\ on Windows, / and /Volumes on macOS/Linux) to block traversal exploits.
• Headless Process Sandboxing: Background executions run with CREATE_NO_WINDOW (on Windows) and concurrency mutex locks to prevent desktop UI disruption and runaway process cascades.

---

📱 Mobile UI Features

Feature	Description
Antigravity Quota Monitor	Seamless dashboard card showing active model (e.g., Gemini 3.8 Flash (High)), 5-hour session quota, and weekly limits with exact countdown timers (Resets in Xh Ym) and on-demand refresh.
Voice-to-Text Dictation	One-tap voice prompt bar utilizing native audio recording and host-side ffmpeg + speech recognition for hands-free agent steering.
Workspace Selector	Interactive multi-drive breadcrumb navigation modal (C:\, D:\ on Windows, / on macOS/Linux) to effortlessly switch project folders without touching your workstation.
Session Resume	Direct integration with Antigravity SQLite database to resume prior chat conversations by summary and timestamp.
Quick Action Toolbar	Dedicated touch buttons for Ctrl+C (SIGINT interrupt), Enter, and workspace/resume management.

---

🧪 Testing & Verification

GravityDesk includes an automated integration test suite verifying authentication entropy, PTY process lifecycle, path traversal boundaries, and endpoint security:

# Run the integration test suite
python -m pytest tests/

All tests execute synchronously against the FastAPI test harness with zero network overhead.

---

📂 Project Structure

GravityDesk/
├── assets/                    # Brand assets, preview banner & UI screenshots
│   ├── logo.png               # Official Astro-Orb mascot logo (512x512)
│   ├── logo.ico               # Windows application & taskbar icon
│   ├── social-preview.png     # Repository social preview banner
│   ├── server-view.png        # Desktop Control Center screenshot
│   ├── home-view.jpeg         # Mobile dashboard & quota telemetry screenshot
│   └── terminal-view.jpeg     # Mobile terminal & voice screenshot
├── server/                    # Backend daemon bounded context
│   ├── cli.py                 # Global CLI launcher & argument dispatcher
│   ├── config.py              # Centralized user config directory & paths (~/.gravitydesk/)
│   ├── main.py                # FastAPI app, REST endpoints, WebSocket hub
│   ├── terminal.py            # Dual-engine PTY runner (ConPTY & Unix PTY)
│   ├── antigravity.py         # AGY active model reader & quota telemetry
│   ├── system.py              # Telemetry vitals & sleep inhibitor
│   ├── network.py             # Tailscale IP resolver, token generator & QR
│   ├── conversations.py       # AGY SQLite resume & session sync
│   ├── workspaces.py          # Directory explorer & path safety validation
│   ├── devices.py             # Mobile device pairing & identity registry
│   └── gui.py                 # Desktop GUI Control Center (Tkinter)
├── mobile/                    # React Native / Expo client bounded context
│   ├── App.tsx                # Main mobile application entrypoint
│   └── src/
│       ├── screens/           # Tab screens (HomeScreen, TerminalScreen)
│       ├── components/        # UI components (TerminalView, PromptBar, Modals)
│       ├── api/               # Typed REST API & WebSocket client
│       ├── hooks/             # Terminal, vitals, and pairing lifecycle hooks
│       ├── storage/           # Token and device persistence (expo-secure-store)
│       └── types/             # Domain TypeScript interfaces
├── tests/                     # Integration test suite
│   └── test_server.py         # Security, PTY, and endpoint harness
├── app.py                     # Unified application launcher (GUI & Headless)
├── requirements.txt           # Python package dependencies
├── LICENSE                    # MIT Open Source License
└── AGENTS.md                  # Autonomous agent operational manual

---

🛣️ Roadmap

• Dual-engine terminal runner (Windows ConPTY & Unix POSIX PTY) with async WebSocket streaming
• Tailscale auto-detection & 256-bit token authentication
• Real-time hardware vitals (CPU, RAM, Battery, AC status)
• Dynamic QR Code pairing & Instant Access Revocation
• Modern Tkinter Desktop Control Center
• AGY conversation history sync from SQLite
• Mobile WhatsApp-style multiline prompt bar & Voice STT pipeline
• Real-time Antigravity engine active model & quota usage telemetry (/usage)
• Zero-popup headless background execution (CREATE_NO_WINDOW)
• Multi-drive breadcrumb workspace explorer
• Official Astro-Orb brand identity & adaptive Android icon
• Standalone Android APK build (expo prebuild / EAS)
• Multi-OS host support (Windows, macOS & Linux)
• Push notification alerts on AGY prompt completion or error
• Biometric fingerprint authentication on mobile app

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Developed as a high-performance developer tool for the Google Antigravity ecosystem.