Antigravity CLI Remote Control Syncs Your Agent

Environment Note: This setup runs on Antigravity CLI (agy) v1.2.13 on Apple Silicon macOS with Nix-darwin and Home Manager, powered by Google Gemini 3.8 Flash with architecture staged for the upcoming Gemini 4 Pro model tier.

Here is a scenario every developer working with agentic coding tools recognizes:

You spend the afternoon at a coffee shop working on your MacBook Pro. You pair with your AI agent to untangle a subtle concurrency bug, plan a multi-file refactor, and run diagnostic experiments. By evening, you commit your code and head home.

You sit down at your desk, fire up your Mac mini with dual displays, and run git pull. Your repository updates instantly.

Then you launch your agent in the terminal to resume work.

The repository is synchronized, but your agent has complete amnesia. The entire conversation thread, the reasoning trajectory, the scratchpad tests, and the execution context remain trapped on your laptop disk. You spend the next ten minutes summarizing what you already solved just to bring your desktop agent back up to speed.

Code synchronization is solved. Agent state synchronization is not.

The Temptation: Why Not Just Sync ~/.gemini? #

The instinctive engineering reaction is simple: put ~/.gemini/antigravity-cli/ into Syncthing, Dropbox, or a shared Git repository.

Do not do this. It breaks almost immediately for three architectural reasons:

1. SQLite Write-Ahead Logging (WAL) Collisions: Antigravity CLI stores sessions in SQLite databases (conversation_summaries.db and per-session conversations/<uuid>.db). Active SQLite WAL files (.db-wal and .db-shm) require shared memory and filesystem-level lock integrity. Bi-directional file syncing across live nodes triggers lock conflicts, split-brain states, and corrupted conversation trees.
2. OAuth Token Invalidation: Files like antigravity-oauth-token and mcp_oauth_tokens.json store active OAuth sessions tied to a specific machine identity and refresh lifecycle. Concurrently syncing credentials between active machines leads to race conditions and cross-machine session revocation.
3. Workspace Path Dependencies: Conversations record absolute file URIs (file:///Users/...). Any slight deviation in user path or directory layout causes the CLI to misplace active workspace anchors.

Trying to treat local AI CLI state as a peer-to-peer file sync problem is a dead end.

The Inversion: Antigravity CLI Remote Control #

The solution is not to sync database files between two computers. The solution is to pick one computer as the permanent source of truth and access it remotely.

Instead of running Antigravity CLI locally on my MacBook Pro, my M6 Mac mini at home acts as a dedicated, always-on AI workstation. The Mac mini hosts the repositories, compilers, and the active Antigravity runtime.

To bridge the laptop to the desktop, Antigravity CLI provides the remote serving command:

agy remote-control serve --name "mac-mini"

The --name flag assigns an explicit instance label shown in the Antigravity web interface, preventing device confusion when managing multiple workstations. (You can also configure this declaratively via cliRemoteControlHostname in ~/.gemini/config/config.json).

When this runs on the Mac mini, it establishes an authenticated, encrypted tunnel directly into Google’s Antigravity infrastructure. From my MacBook Pro, iPad, or any web browser, I connect directly to the active session via https://antigravity.google.com.

The benefits are immediate:

• Persistent Memory: The conversation never stops. When I close my laptop at the coffee shop and open my desktop at home, the agent is exactly where I left it.
• Zero Battery or Thermal Drain: Autonomous agent cascades powered by Google Gemini 3.8 Flash (and prepared for the massive context windows and deep reasoning of the upcoming Gemini 4 Pro) execute rapid tool-calling loops, multi-file inspections, and compiler builds. Offloading these continuous agentic workloads to desktop silicon on wall power keeps your laptop cold, silent, and battery-efficient.
• Lid-Closure Resilience: When you close your laptop to catch a bus, long-running agent tasks keep humming along without dropping network connections or aborting mid-step.

Why Remote Control Beats Plain SSH #

A natural question arises: why not simply SSH into the Mac mini and run agy inside a terminal multiplexer like tmux or zellij?

While SSH remains a staple of remote administration, pairing with an autonomous AI agent over plain terminal SSH breaks down across two critical dimensions:

1. Immunity to Sporadic Internet Connections: Standard SSH connections are notoriously fragile. When tethering on a train, switching between Wi-Fi access points, or encountering packet loss, SSH sessions freeze, pipe errors occur, and re-attaching requires manual intervention. In contrast, Antigravity Remote Control routes state through Google’s resilient HTTPS/WebSocket relay. When your laptop sleeps, drops connection, or roams between networks, the web interface automatically reconnects and rehydrates the full conversational history without dropping a single byte or interrupting running tasks.
2. Native Visual and Multimodal Rendering: A terminal emulator is fundamentally restricted to text, ANSI escape codes, and coarse ASCII blocks. It cannot natively render formatted Markdown documents, interactive Mermaid diagrams, SVG vector graphics, or generated raster images (.png, .jpg). The Antigravity Web Interface renders rich Markdown artifacts with full typographic hierarchy, responsive tables, interactive diagrams, and visual images directly in the side panel, delivering a visual workspace that terminal SSH cannot match.

Declarative Automation with Nix and macOS LaunchAgents #

Managing background daemons manually defeats the purpose of an always-on workstation. In my nix-config setup, the remote daemon runs declaratively via Home Manager:

# hosts/mac-mini/home.nix
launchd.agents.antigravity-cli-daemon = {
  enable = true;
  config = {
    ProgramArguments = [
      "/bin/sh"
      "-c"
      "exec ${config.home.homeDirectory}/.local/bin/agy remote-control serve"
    ];
    KeepAlive = {
      SuccessfulExit = false;
    };
    RunAtLoad = true;
    StandardOutPath = "${config.home.homeDirectory}/Library/Logs/antigravity-cli-daemon.log";
    StandardErrorPath = "${config.home.homeDirectory}/Library/Logs/antigravity-cli-daemon.log";
  };
};

Because Antigravity Remote Control runs as a LaunchAgent under the macOS GUI domain (gui/501), it launches automatically at user login and restarts if the process ever halts.

Unattended Autonomy #

Operating remotely means you cannot constantly click “Approve” prompts in a terminal. In ~/.gemini/antigravity-cli/settings.json (also managed via Nix), I grant automatic execution permissions scoped strictly to my active project repositories:

{
  "toolPermission": "always-proceed",
  "allowNonWorkspaceAccess": true,
  "permissions": {
    "allow": [
      "command(*)",
      "read_file(*)",
      "write_file(*)",
      "mcp(*)",
      "read_url(*)"
    ]
  },
  "trustedWorkspaces": [
    "/Users/wjkoh/wjkoh.github.io",
    "/Users/wjkoh/nix-config"
  ]
}

This configuration permits the agent to write files, run tests, and execute tool calls autonomously without stalling for approval while I am away from my desk.

Managing Workspaces: Projects and Git Worktrees #

When connecting to Antigravity Remote Control from your browser for the first time, proper workspace structuring ensures clean agent behavior:

1. One Project per Git Repository: Rather than bundling multiple paths into a single monolithic view, create a dedicated Project in the web interface for each Git repository residing on your remote host.
2. Context-Scoped Conversations: Within each Project, spin up fresh conversations corresponding to the specific repository and task you are addressing. This cleanly isolates workspace indexes, file watcher boundaries, and conversational reasoning trees without cross-project context pollution.

Native Support for Git Worktrees #

A major capability of the Antigravity web interface combined with agy remote-control is first-class support for git worktree.

When you need to develop an experimental feature, investigate a bug, or run exploratory tests without disturbing your primary working tree, you do not need to stash local changes or interrupt existing builds. Create a linked worktree on the remote host:

git worktree add ../app-feature-experiment feature-experiment

You can bind a dedicated Project or workspace session directly to that worktree directory. The remote daemon executes compiler passes, tests, and diffs inside that isolated branch path. This architecture enables concurrent, multi-branch agentic development on your home workstation while you review and steer progress from a lightweight browser tab on your laptop.

Remote Capabilities: MCP Inheritance and Chrome Browser Automation #

Connecting through Antigravity Remote Control brings access to your workstation’s complete runtime environment.

Zero-Configuration MCP Inheritance #

The remote session automatically inherits every Model Context Protocol (MCP) server already configured on the host machine. Whether you use the Google Workspace MCP for calendar and email coordination, Bright Data for web intelligence, or local database connectors, they execute natively on the host:

• You do not need to re-authenticate tokens on your laptop.
• You do not need to expose local ports or sync API credentials across devices.
• The host CLI executes tool calls directly against its local network and filesystem permissions.

Browser Mode & Chrome Remote Debugging on the Host #

If you use Antigravity’s Browser Mode (/browser) through the remote web interface to inspect web applications, take visual snapshots, or test UI workflows, the host machine must allow the agent to drive Google Chrome.

Antigravity automates Chrome via the Chrome DevTools Protocol (CDP). For the remote daemon on your Mac mini to connect to Chrome, Chrome must be launched with remote debugging enabled:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cache/agy-chrome-profile" \
  --remote-allow-origins="*"

Key considerations for headless workstations:

• --remote-debugging-port=9222: Opens the local CDP WebSocket server that Antigravity connects to for DOM extraction and UI interactions.
• --user-data-dir: Essential for isolation. Modern Chrome disables remote debugging on the default user profile and refuses to open a debugging port if a standard Chrome window is already running without a dedicated profile path.
• --remote-allow-origins="*": Prevents Chrome from rejecting the incoming WebSocket handshake due to CORS origin checks.
• First-Time Authorization: When Antigravity attaches over CDP, Chrome displays the automated software warning banner (“Chrome is currently controlled by automated test software”). Clicking Allow authorizes the session.

On an always-on Mac mini, you can keep a lightweight Chrome instance running under launchd so the agent can execute browser tools immediately without requiring manual browser launches.

The File-Viewing Tradeoff: The Markdown-First Strategy #

The Antigravity web interface excels across visual mediums:

• Rich Markdown Documents: Formatted with clean typography, headers, lists, and responsive tables.
• Vector and Graphic Assets: Natively renders SVG vector files, interactive Mermaid architecture diagrams, and embedded raster images (.png, .jpg, .webp).
• Visual Diff Overlays: Displays file modifications with clear side-by-side or unified green/red diff views, far surpassing terminal text output.

Its only notable shortcoming is native PDF viewing. Because the web interface cannot directly stream and render compiled PDF binaries residing on the remote host’s filesystem, previewing a compiled document in the browser is currently unsupported.

This limitation is minor, and the workaround is simple: adopt a strict Markdown-First Artifact Strategy.

1. Draft and Review via Markdown Artifacts: While composing, editing, and structuring documents, instruct the agent to output Markdown (.md) artifacts. The Antigravity Artifact Window renders the complete document live with rich formatting and diagram support. You review, critique, and iterate entirely inside the web interface without touching external viewers.
2. Compile to PDF Only Upon Final Sign-Off: Once the text, structure, and tables are approved, instruct the agent to run the host compiler (typst compile ... or pdflatex ...) to produce the authoritative .pdf directly on the host disk.

This workflow turns a minor viewing constraint into an efficient drafting discipline: fast visual iteration in the browser, followed by final laser-ready compilation on the workstation.

The Headless Mac Mini Gotcha: FileVault #

Running an Apple Silicon Mac mini without a display introduces one critical trap: FileVault pre-boot disk encryption.

If you restart a headless Mac mini remotely over SSH using a regular sudo reboot, the machine reboots into the FileVault pre-boot environment. In this state, disk storage remains encrypted, networking never initializes, and background LaunchAgents cannot start. You are locked out until someone physically plugs in a keyboard and types your password.

To make remote restarts safe, always invoke authenticated restart:

sudo fdesetup authrestart

This command caches the decryption key in the Secure Enclave for that specific reboot. Paired with macOS automatic login, the machine bypasses both the pre-boot barrier and the login screen, booting straight into the user GUI domain (gui/501) where the agy LaunchAgent immediately resumes serving.

Summary #

In modern AI-assisted engineering, the code repository is only half the state. The other half is the conversational reasoning context of your agent.

By switching from isolated local sessions to Antigravity CLI Remote Control on desktop hardware, you get the best of both worlds: complete portability on the road, and an uninterrupted, continuous AI partnership when you sit back down at your desk.