Running Antigravity in WSL2 on Windows combines the best of both worlds — a Linux development environment with Windows desktop integration. But the setup isn't smooth out of the box. Broken launchers, OAuth failures, sandbox conflicts, and memory issues are all well-documented by the community. This guide provides verified fixes for every issue.
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
1. Prerequisites
# Check WSL version (must be WSL2, not WSL1)
wsl --list --verbose
# If WSL2 isn't installed:
wsl --install
# Reboot after installation
# Verify WSL2 is running
wsl --list --verbose
# Should show VERSION 2 for your distro
2. Installation Steps
Option 1: Install on Windows (connects to WSL2 via Remote)
Download Antigravity for Windows from the official site
Use Remote-SSH or Remote-WSL to connect to your WSL2 distro
Option 2: Install the Antigravity CLI (agy) inside WSL2
# Inside your WSL2 terminal:
curl -fsSL https://antigravity.dev/install.sh | bash
agy auth login
# Note: the Gemini CLI sunset for individuals on June 18, 2026.
# Its agent workflows now live in the agy CLI — don't
# install @google/gemini-cli for Antigravity work anymore.
3. Fix: Broken agy CLI Launcher
The Antigravity CLI (agy) on WSL often fails out of the box because some Windows installer builds ship without the scripts that bridge Windows and WSL. The quickest fix is copying the missing scripts from VS Code:
# Check if agy is in your PATH
which agy
# If not found, add to PATH manually:
export PATH="$PATH:/mnt/c/Users/YOU/AppData/Local/Programs/Antigravity/bin"
# Make the fix permanent
echo 'export PATH="$PATH:/mnt/c/Users/YOU/AppData/Local/Programs/Antigravity/bin"' >> ~/.bashrc
# If agy still fails, copy launcher scripts from VS Code:
cp /mnt/c/Users/YOU/AppData/Local/Programs/"Microsoft VS Code"/bin/* \
/mnt/c/Users/YOU/AppData/Local/Programs/Antigravity/bin/
4. Fix: Authentication / OAuth Errors
Google's OAuth 2.0 is sensitive to time drift, and WSL2 clocks frequently drift when a laptop sleeps. This causes tokens to be rejected as expired, resulting in sudden authentication failures.
# Check current WSL2 time vs actual time
date
# Fix 1: Sync with hardware clock
sudo hwclock -s
# Fix 2: Force NTP sync
sudo ntpdate time.google.com
# Fix 3: Permanent fix — add to .bashrc
echo 'sudo hwclock -s 2>/dev/null' >> ~/.bashrc
# Then re-authenticate (agy CLI)
agy auth login
One WSL2-specific trap: the OAuth callback is served on a localhost port inside the Linux VM, but under WSL2's default NAT networking your Windows browser resolves localhost to Windows, not to the VM. If the sign-in tab hangs on "waiting for authentication," copy the full callback URL from the terminal and paste it into the browser manually, or enable mirrored networking (see the file-watching section below) so 127.0.0.1 maps to the same host on both sides.
For other authentication issues, see our sign-in troubleshooting guide.
5. Fix: Sandbox Mode Issues (v1.21.6)
The v1.21.6 update introduced Linux sandboxing that requires user namespaces. Some hardened Linux distributions (and WSL2 configurations) disable unprivileged user namespaces, causing the renderer to crash.
# Check if user namespaces are enabled
sysctl kernel.unprivileged_userns_clone
# If value is 0, enable it:
sudo sysctl -w kernel.unprivileged_userns_clone=1
# Make permanent:
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
# Alternative: launch without sandbox (less secure)
antigravity --no-sandbox
For all v1.21.6 issues, see our dedicated v1.21.6 fix guide.
6. Memory Management
WSL2 will consume as much memory as the Windows host allows, which can cause Antigravity crashes when WSL eats too much RAM. Set a memory cap in .wslconfig:
# Create/edit %USERPROFILE%\.wslconfig
# (e.g., C:\Users\YOU\.wslconfig)
[wsl2]
memory=8GB # Cap WSL2 at 8GB RAM
processors=4 # Limit CPU cores
swap=4GB # Swap file size
localhostForwarding=true
# Apply changes:
wsl --shutdown
# Then reopen your WSL2 terminal
7. Slow Performance & Broken File Watching
This is the single biggest reason WSL2 feels sluggish with Antigravity, and it has nothing to do with the model quota. If git status takes tens of seconds, the agent's file indexer stalls, or your dev server never hot-reloads, the cause is almost always where the project lives on disk and how many files WSL2 is trying to watch.
Why /mnt/c is slow: the \\wsl$ filesystem boundary
WSL2 is a real Linux VM with its own ext4 disk (a virtual .vhdx). Your Windows drives are not part of that disk — they are exposed into the VM over the 9P protocol (Plan 9), the same mechanism that powers the \\wsl$ / \\wsl.localhost shares you see in Windows Explorer. Every time a tool under /mnt/c/... reads a directory, it isn't talking to disk directly — it's acting as a network client crossing the Windows–Linux boundary. On a tree walk like git status or an agent index pass, that round-trip per file produces 10× or worse slowdowns. The boundary is directional too: Windows reading Linux files (\\wsl$) is fast, but Linux reading Windows files (/mnt/c) is the slow path.
The fix is to keep the project on the ext4-native filesystem, under your Linux home (~/), never under /mnt/c. Use df -T . to confirm: ext4 is native and fast; 9p or drvfs means you are on the slow cross-boundary path.
# Check which filesystem your project is on
df -T .
# ext4 = native (good) | 9p / drvfs = cross-boundary (slow)
# Move the repo off /mnt/c onto the Linux disk
mv /mnt/c/Users/YOU/projects/myapp ~/projects/myapp
cd ~/projects/myapp
# Reinstall deps INSIDE Linux — node_modules built on
# NTFS carries broken symlinks/permissions across 9P
rm -rf node_modules && npm install
# Open Antigravity from the ext4 path, not the Windows one
agy .
Broken file watching: raise the inotify limit and exclude heavy dirs
File watching on Linux uses inotify, and each watched file consumes a watch slot. A single Node project with node_modules plus .next and dist can blow past the default limit, which surfaces as an ENOSPC: System limit for number of file watchers reached error, silent hot-reload failures, or the agent missing edits you just made. Two changes fix it: raise the kernel limit, and tell the editor to stop watching build output.
First, exclude the noisy directories in your workspace settings.json (.antigravity/settings.json or the shared VS Code settings the editor reads). Excluding them from files.watcherExclude both frees watch slots and stops the agent from re-indexing regenerated files:
{
"files.watcherExclude": {
"**/node_modules/**": true,
"**/.next/**": true,
"**/dist/**": true,
"**/.git/objects/**": true,
"**/build/**": true
}
}
Then raise the kernel watch limit so large trees don't exhaust it. On WSL2 this must be applied inside the distro and survives across reboots via /etc/sysctl.conf:
# Persist a higher limit
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
echo 'fs.inotify.max_user_instances=512' | sudo tee -a /etc/sysctl.conf
# Apply now, then fully restart WSL2 so it sticks
sudo sysctl -p
# From PowerShell: wsl --shutdown
8. Performance Optimization
- Store projects on ext4, not
/mnt/c: Covered in depth above — this is the single highest-impact change. See Slow Performance & Broken File Watching. - Configure .antigravityignore aggressively: Add
node_modules/,.git/,dist/, andbuild/to prevent the agent from indexing heavy directories. See our agent loading guide. - Disable Windows Defender real-time scanning for dev folders: Add your WSL2 project paths to Defender exclusions. The real-time scanner creates significant I/O overhead.
- Use systemd for WSL2: Enable systemd in
/etc/wsl.confwith[boot] systemd=truefor better service management. - Restart WSL regularly:
wsl --shutdownfrom PowerShell clears accumulated memory and process bloat.
9. Browser Subagent on WSL2 (the localhost barrier)
Antigravity 2.0's Browser subagent does not spin up a headless Chromium inside Linux — you do not need an X server, WSLg, or chromium-browser. It drives the real Chrome on your Windows host through the Antigravity browser extension. The extension exposes a small local server, and the subagent connects to Chrome over the DevTools Protocol (CDP). Both endpoints listen on localhost ports on the Windows side.
That is exactly where WSL2 trips people up. When Antigravity runs inside the Linux VM but Chrome and the extension run on Windows, the subagent tries to reach the extension/CDP endpoint at localhost — but under WSL2's default NAT networking, localhost inside the VM points at the VM itself, not at Windows. The connection just fails, and the browser task hangs or reports it can't attach to a browser. (Note the asymmetry: localhostForwarding makes Windows→WSL work, but it does not give WSL→Windows the same courtesy.)
The clean fix on Windows 11 22H2+ is mirrored networking, which makes 127.0.0.1 resolve to the same host on both sides so the subagent can reach the extension on Windows:
# %USERPROFILE%\.wslconfig (Windows 11 22H2+)
[wsl2]
networkingMode=mirrored
# Apply from PowerShell
wsl --shutdown
# On older Windows / NAT mode, target the Windows host IP
# instead of localhost:
cat /etc/resolv.conf | grep nameserver
# (that nameserver IP is your Windows host from inside WSL2)
The most reliable setup overall is to keep it single-sided: run the Antigravity IDE on Windows and connect into WSL2 over Remote for your code, so the Browser subagent, the extension, and Chrome all sit on the same Windows host and never cross the network boundary. Reserve the mirrored-networking route for when you specifically want the agent process itself living inside Linux.