How I Got Google Antigravity Working Perfectly with WSL

As a Data Engineer, I spend most of my life in the terminal. Whether I'm optimizing Spark queries or building Python-based Gen AI tools (like my recent work on AI-Hub), Windows Subsystem for Linux (WSL) is non-negotiable. It gives me the rich ecosystem of Linux with the productivity of Windows.

Why WSL? WSL gives you a full Linux kernel on Windows—meaning bash scripts and containers run exactly as they would in production (like Google Cloud). No dual-booting, no VMs. Just native Linux tooling with Windows convenience.

Recently, I started exploring Google Antigravity IDE, Google’s new agent-first development environment. It looks promising for building AI agents, but out of the box, it didn't play nice with my WSL setup. With the massive 2.0 ecosystem refresh, Google renamed the binary to antigravity-ide and moved things around, adding some spaces to Windows installation directories that break basic paths.

If you’re like me and trying to run Linux scripts or Python agents inside Antigravity IDE on Windows, you might hit some frustrating walls. Here is the developer log of how I fixed them—specifically getting the CLI, the workspace, and the browser subagent to work natively in Ubuntu.

---

TL;DR

Quick fix checklist:

1. ✅ Ctrl+Shift+P → "Remote-WSL: Connect to WSL"
2. ✅ Auto-detect paths, update symlink, and patch WSL_EXT_ID to google.antigravity-remote-wsl
3. ✅ Enable mirrored networking via dynamic .wslconfig creation
4. ✅ Install Chrome extension manually if needed
5. ✅ [New] Run the upgraded antigravity-repair script if updates break the host server connection

---

The Problem

I opened a project workspace in Antigravity IDE on Windows. The interface looked great (very VS Code-like), but when I asked the AI agent to run a simple bash command like ls -latr, it choked.

The error was:

text
Invalid command line argument: -l
Please use 'wsl.exe --help' to get a list of supported arguments.

Basically, the Windows-based agent was trying to execute Linux commands via wsl.exe wrappers rather than running them inside Linux. This breaks almost every setup script I use.

---

Step 1: Switch Context, Don't Install

I initially looked for a "WSL Extension" in the marketplace, but the standard Microsoft one wasn't available. It turns out you just need to force Antigravity IDE to look at the "Linux" side of your machine.

1. Open Antigravity IDE.
2. Press Ctrl+Shift+P (Command Palette).
3. Type and select: Remote-WSL: Connect to WSL.

💡 Pro Tip: When the new window opens, make sure you open your project folder using the Linux path (e.g., ~/workspace/dotfiles) rather than the Windows mount path (\\wsl.localhost\...). The Windows mount path (\\wsl.localhost\Ubuntu\home\...) is how Windows accesses your Linux files, but it causes permission issues. Always use the native Linux path (~/...). You'll know it worked when the bottom-left status bar shows your distribution connection state.

---

Step 2: Fixing the CLI (agy)

I prefer launching tools directly from the terminal. But if you run the old launcher inside your WSL terminal, it defaults to opening the Windows version of the app, completely disconnecting you from your Linux environment.

To fix this, we need to handle the new Antigravity IDE folder paths cleanly.

🔄 Migrating/Updating from an Older Setup?

If you read the older version of this guide and already have an active agy link configured, Google's path migration broke it. To seamlessly overwrite your old dead link with the automatic, zero-manual-input path resolution, run this in your WSL prompt:

bash
LOCAL_APP_PATH=$(cmd.exe /c "echo %LOCALAPPDATA%" 2>/dev/null | tr -d '\r')
W_DRIVE=$(wslpath "$LOCAL_APP_PATH")

ln -sf "$W_DRIVE/Programs/Antigravity IDE/bin/antigravity-ide" ~/.local/bin/agy

Starting Fresh? The Manual Patch Checklist:

1. Create an Intelligent Symlink: Instead of typing your Windows username out manually, you can use Windows environment variables over the WSL interoperability layer to bind the shortcut cleanly. Run this from your terminal:

bash
LOCAL_APP_PATH=$(cmd.exe /c "echo %LOCALAPPDATA%" 2>/dev/null | tr -d '\r')
W_DRIVE=$(wslpath "$LOCAL_APP_PATH")

ln -sf "$W_DRIVE/Programs/Antigravity IDE/bin/antigravity-ide" ~/.local/bin/agy

(Make sure ~/.local/bin is exported in your shell's active $PATH configurations inside your .bashrc or .zshrc).

2. Patch the Config: We need to tell the launcher to use Google's specific remote extension ID instead of Microsoft's. Open the config script at %USERPROFILE%\AppData\Local\Programs\Antigravity IDE\bin\antigravity-ide in a text editor and update the core extension pointer variable:

bash
# Old Line (Comment this out)
# WSL_EXT_ID="ms-vscode-remote.remote-wsl"

# New Line
WSL_EXT_ID="google.antigravity-remote-wsl"

3. Add the Helper Scripts: The installer is missing some bootstrap utility script files that the remote extension expects. You can copy them straight from an existing local VS Code installation.

• Source: %USERPROFILE%\.vscode\extensions\ms-vscode-remote.remote-wsl-<latest_version>\scripts\
• Destination: %USERPROFILE%\AppData\Local\Programs\Antigravity IDE\resources\app\extensions\antigravity-remote-wsl\scripts\

(Note: You will likely need to create the scripts folder manually in that destination path).

Now, running agy . inside WSL launches the editor in the correct environment immediately.

---

🚀 Quick Setup: One-Command Automation (Recommended)

Don't want to do Steps 2-3 manually? I've updated my automation script to handle all of the folder changes, whitespace safety variables, and environment configuration automatically.

Run from your WSL terminal:

bash
curl -L https://raw.githubusercontent.com/smaxiso/antigravity-wsl/master/setup-antigravity-wsl.sh | bash

Or download and inspect first:

bash
wget https://raw.githubusercontent.com/smaxiso/antigravity-wsl/master/setup-antigravity-wsl.sh
chmod +x setup-antigravity-wsl.sh
./setup-antigravity-wsl.sh

What the script does:

• ✅ Auto-detects Windows Local AppData paths using cmd.exe variables (no user prompt needed)
• ✅ Automatically handles old symlink overwrites to the new antigravity-ide binary location
• ✅ Patches Antigravity IDE config mappings to use the correct google.antigravity-remote-wsl ID
• ✅ Copies helper scripts from VS Code into the new spaced folder structures safely
• ✅ Enables mirrored networking on your host machine automatically
• ✅ Installs the upgraded antigravity-repair tool automatically (See update below)

📦 View Source on GitHub | 🐛 Report Issues

---

Step 3: The Browser Subagent (Mirrored Networking)

If you are building agents that need to browse the web, the agent might fail to connect to Chrome. This is because WSL usually runs on its own virtual network, so 127.0.0.1 in Linux isn't 127.0.0.1 in Windows.

The fix is to enable Mirrored Networking. Instead of hunting around your Windows File Explorer to find and edit files by hand, you can configure your host setup completely from inside your terminal.

1. Create and append the mirrored config profile instantly: Run this command inside WSL. It will locate your profile using Windows environment variables and append the configuration safely:

bash
cat <<EOF >> $(wslpath $(cmd.exe /c "echo %USERPROFILE%" 2>/dev/null | tr -d '\r'))/.wslconfig
[wsl2]
networkingMode=mirrored
EOF

2. Restart WSL: Open a native Windows PowerShell window and run wsl --shutdown.

After restarting, the Antigravity agent in WSL can see your Windows Chrome browser flawlessly.

---

🔁 Upgraded: Antigravity IDE WSL Breakage After Updates

Even after following the guide above, you might suddenly encounter errors like remote-cli/antigravity-ide: not found or "Remote Extension host terminated unexpectedly". This happens because downstream application updates frequently break the background server bootstrap process.

The Root Cause

Antigravity dynamically builds commit-specific server directories inside Linux (e.g., ~/.antigravity-server/bin/<commit_hash>). Sometimes, an automated update script drops the internal execution bin folder as a dead symlink to an empty path instead of a functional directory. Since the runtime engine cannot write components into a broken symlink, it crashes.

Furthermore, when an update drops a failed .tar.gz archive, old cache loops confuse the standard launch script.

The Auto-Cleaning Solution: antigravity-repair

I completely rewrote the recovery tool. The script now aggressively evaluates the cache: if it detects a failed update download (tarball), it automatically purges the old server directories to clear the update loops, force-creates the missing binary target layouts, and hooks your working VS Code server engine straight to the brand new antigravity-ide core.

Save this script as ~/.local/bin/antigravity-repair:

bash
#!/usr/bin/env bash
set -e

# Detect local VS Code commit
VS_COMMIT="$(ls -1 ~/.vscode-server/bin 2>/dev/null | head -n1)"
if [[ -z "$VS_COMMIT" ]]; then
    echo "❌ No VS Code server found. Run 'code .' first."
    exit 1
fi

# Updated to target the new IDE server directory
AG_BIN_DIR="$HOME/.antigravity-ide-server/bin"
mkdir -p "$AG_BIN_DIR"

# 1. ALWAYS check for failed downloads (tarballs) FIRST.
FAILED_TAR=$(ls -1 "$AG_BIN_DIR"/*.tar.gz 2>/dev/null | head -n1)

if [[ -n "$FAILED_TAR" ]]; then
    FILENAME=$(basename "$FAILED_TAR")
    RECOVERED_COMMIT="${FILENAME:0:40}"

    echo "⚠️  Update detected! Found failed download artifact: $FILENAME"
    echo "🧹 Cleaning up old server cache..."

    # Delete old server directories to prevent update loops
    find "$AG_BIN_DIR" -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +

    echo "🔨 Force-creating directory for new commit: $RECOVERED_COMMIT"
    mkdir -p "$AG_BIN_DIR/$RECOVERED_COMMIT"

    # Cleanup the bad file
    rm -f "$FAILED_TAR"
fi

# 2. Gather directories
AG_DIRS=$(find "$AG_BIN_DIR" -maxdepth 1 -mindepth 1 -type d 2>/dev/null || true)

if [[ -z "$AG_DIRS" ]]; then
  echo "❌ No Antigravity directories or artifacts found."
  echo "👉 Run 'agy .' once to generate them."
  exit 1
fi

echo "🔧 Repairing Antigravity WSL server..."
echo "   VS_COMMIT=$VS_COMMIT"

for AG_BASE in $AG_DIRS; do
  AG_COMMIT=$(basename "$AG_BASE")

  # Skip non-server dirs
  if [[ ! -f "$AG_BASE/product.json" && ! -e "$AG_BASE/bin" && "$AG_BASE" != *"$RECOVERED_COMMIT"* ]]; then
      continue
  fi

  echo "   → Patching $AG_COMMIT"

  # 1. Fix symlink bug
  if [[ -L "$AG_BASE/bin" ]]; then
    rm "$AG_BASE/bin"
    mkdir -p "$AG_BASE/bin"
  fi

  # 2. Create structure
  mkdir -p "$AG_BASE/bin/remote-cli"

  # 3. Link binaries to the updated antigravity-ide ecosystem identity
  ln -sf \
    "$HOME/.vscode-server/bin/$VS_COMMIT/bin/remote-cli/code" \
    "$AG_BASE/bin/remote-cli/antigravity-ide"
done

echo ""
echo "=================================================="
echo "✔ Antigravity WSL server successfully repaired! 🚀"
echo "=================================================="
echo ""
echo "⚠️  IMPORTANT NEXT STEPS:"
echo "1. Open Windows PowerShell and run: wsl --shutdown"
echo "2. Re-open your Ubuntu terminal."
echo "3. Run 'agy .' again."
echo ""

Make it executable: chmod +x ~/.local/bin/antigravity-repair.

How to use it: If your agy shell alias ever hangs or spits a 404/not-found error after Google runs an app update:

1. Run antigravity-repair inside your WSL environment.
2. Complete the printed instruction steps (run wsl --shutdown in standard PowerShell).
3. Re-open your shell and type agy .—it will pop right up.

---

📁 Workspace Performance Best Practice

Another important lesson learned: **Do not develop inside /mnt/c**.

If you keep your projects in C:\Users\YourName\Workspace (/mnt/c/...), tools like Git, Python, and Node will be painfully slow because every single file operation has to cross the heavy NTFS-to-Linux translation bridge.

The Correct Layout:

1. Store code directly inside Linux: ~/workspace (This uses the native, high-performance ext4 filesystem).
2. Access from Windows: Open File Explorer and navigate directly to \\wsl.localhost\Ubuntu\home\<your_user>\workspace.

This configuration gives you blazing-fast execution speeds for data processing and scripts while keeping files fully accessible to Windows applications.

---

💡 Data & Context Migration Note

If you've been using Antigravity for a while and find that your prompt history, indexing parameters, or workspace sidebar states didn't automatically migrate over into the new 2.0 Antigravity IDE release, don't worry. There is an excellent guide over on Reddit detailing exactly how to safely map your legacy profile directories over to the fresh client layout without corruption loops. You can check out the full Reddit migration and discussion thread here.

---

Final Thoughts

Antigravity IDE mixed with native WSL optimization creates a stellar environment for engineering pipelines and designing localized AI agents on Windows. With these path updates and the auto-cleaning repair logic locked down, you completely sidestep the maintenance headaches that usually come with rapid release cycles.

Hit any edge cases or strange error dumps? Drop a comment or reach out—I'll keep this guide patched as the IDE platform changes!

Happy coding! 🚀