Back to Resources
Platform Architecture & Remote Devbox GuideLast Updated: Published November 20, 2026

Google Antigravity Remote Workspaces: SSH Devboxes and Container Sync

Google Antigravity connects to remote 64-bit Linux devboxes (glibc 2.26+) over OpenSSH by installing ~/.antigravity-hub-server/ on the host and loading skills, rules, and MCP servers directly from remote ~/.gemini/ and .agents/skills/ paths. To prevent skill loss across SSH hosts and Docker containers, avoid musl Alpine images, bind-mount ~/.gemini/config/skills/ in devcontainer.json, or sync one library via Prompttly.

OpenSSH Devboxes
glibc Dev Containers
Cloud Skill Sync

Losing local skills when connecting Google Antigravity over SSH or into Docker containers? Sync ~/.gemini/config/skills, fix musl/SSH errors, and avoid drift.

How Does Google Antigravity Connect to a Remote Workspace Over SSH?

Google Antigravity connects to a remote workspace over OpenSSH by splitting the local desktop UI from a persistent hub server installed automatically at ~/.antigravity-hub-server/ on the remote Linux machine. Introduced in Antigravity App v2.33.0+, the Connect over SSH architecture runs all agent tools, Git worktrees, sidecar terminals, and customization discovery directly on the remote host rather than streaming files back to your laptop.

As documented in the official Google Antigravity Connect over SSH documentation: “Antigravity sets up its remote server automatically over OpenSSH so your projects, agents, Git worktrees, terminals, and customizations run directly on the host, and running agents keep working even if you close the window or put your laptop to sleep.” You launch a remote session with antigravity --ssh-host=<destination>, through the Command Palette (Cmd+Shift+P on macOS), or from the Projects sidebar.

Because execution moves entirely to the remote box, Google Antigravity stops reading your local Mac’s ~/.gemini/config/skills/ directory for that window. Every global skill, hook, plugin, and Model Context Protocol (MCP) server must exist inside ~/.gemini/ on the remote host or inside the project’s .agents/skills/ folder—with sidecar panels and MCP OAuth sign-ins relayed securely through the SSH tunnel.

# Launch an isolated Antigravity remote workspace window from macOS
antigravity --ssh-host=gpu-devbox

# Expected directory split on the remote 64-bit Linux host
~/.antigravity-hub-server/         # Remote hub binary + data/ls-*.log diagnostics
~/.gemini/config/skills/           # Global skills shared by Antigravity App & CLI
~/.gemini/config/plugins/          # Installed plugin bundles and MCP configs
<workspace-root>/.agents/skills/   # Repo-scoped skills (legacy .agent/skills/ supported)

Remote Execution Options: Local Mac vs. SSH Devbox vs. Docker Container

Choosing between a local Antigravity window, an OpenSSH devbox, a Docker container, and Remote Control determines where your SKILL.md files resolve and whether background subagents survive a disconnected laptop. Each topology enforces different filesystem boundaries for global and workspace-scoped instructions.

TopologyRuntime HostSkill Discovery PathsDisconnect PersistenceBest Workload
Local Antigravity WindowDeveloper macOS, Windows, or Linux workstation~/.gemini/config/skills/ and <repo>/.agents/skills/Stops when local machine sleeps or powers offLightweight repos, offline editing, and Mac hotkey workflows
Antigravity Connect over SSHRemote 64-bit Linux devbox (x86_64 or arm64, glibc 2.26+)Remote ~/.gemini/ and remote <repo>/.agents/skills/Survives laptop sleep and closed windows until Stop SSH ServerHeavy builds, GPU boxes, and persistent background subagents
SSH Host + Docker Dev Containerglibc Linux container running on the remote SSH hostContainer ~/.gemini/config/skills/ (requires bind mount or sync)Ephemeral filesystem unless mounted via devcontainer.jsonReproducible team toolchains and isolated runtime dependencies
Antigravity Remote ControlYour existing always-on desktop or self-hosted serverHost ~/.gemini/config/skills/ and ~/.gemini/antigravity-cli/skills/Persistent on host; driven from any web browserChecking running CLI or desktop agent sessions from another device

Notice the critical distinction in the Google Antigravity Agent Skills specification: “Antigravity defaults to .agents/skills, but still maintains backward compatibility for .agent/skills.” Meanwhile, global skills live in ~/.gemini/config/skills/ so both the Antigravity App and Antigravity CLI share one remote folder. For a complete breakdown of parent-folder overrides inside monorepos, see our guide to configuring custom workspace skills in Google Antigravity.

Why Do Alpine Containers and Misconfigured SSH Hosts Fail Antigravity?

Google Antigravity remote connections fail primarily when the target environment uses musl libc (such as Alpine Linux containers), disables TCP forwarding in sshd_config, or slows down non-interactive shell startup past the 10-second timeout. The Antigravity hub server strictly requires 64-bit Linux (x86_64 or arm64) running glibc 2.26 or newer—covering Ubuntu 18.04+, Debian 10+, and RHEL 8+.

In addition to OS library requirements, Antigravity overrides seven OpenSSH client flags on every invocation: ForwardAgent=no, ForwardX11=no, ControlMaster=no, ControlPath=none, RemoteCommand=none, ServerAliveInterval=15, and ServerAliveCountMax=3. That means relying on multiplexed ControlMaster sockets or agent forwarding inside ~/.ssh/config will be ignored, and any bastion or ProxyJump host along the route must permit AllowTcpForwarding yes or local.

Antigravity Error CodeRoot Cause on Devbox or ContainerVerified Remediation
UNSUPPORTED_HOSTRemote OS or container uses 32-bit arch, macOS/Windows target, or musl libc (Alpine Linux) instead of glibc 2.26+.Switch container base image to Debian 10+, Ubuntu 18.04+, or RHEL 8+ on x86_64 or arm64.
FORWARDING_PROHIBITEDOpenSSH daemon disables TCP port forwarding required to relay sidecar panels and MCP OAuth sign-ins.Set AllowTcpForwarding yes (or local) in /etc/ssh/sshd_config on the target host and any ProxyJump bastion.
SHARED_HOME_UNSUPPORTEDMultiple cluster nodes mount the same networked $HOME directory (NFS/EFS) where ~/.antigravity-hub-server/ locks collide.Click Take Over to move the server lock, or assign an isolated $HOME path per devbox.
INSTALL_FAILED$HOME is mounted noexec, disk is full, gzip is missing, or ~/.bashrc emits interactive output on login.Verify mount flags and df -h ~, install gzip, and guard interactive shell code behind [ -t 0 ].
LS_START_FAILED / LS_STOPPEDThe remote server binary crashed or timed out after the 10s $SHELL -l -i environment resolution window.Inspect ~/.antigravity-hub-server/data/ls-*.log and skip slow shell prompts when ANTIGRAVITY_RESOLVING_ENVIRONMENT=1.

When Antigravity starts on a remote devbox, it resolves environment variables by executing $SHELL -l -i with a hard 10-second timeout. Heavy prompt themes, NVM initialization, or unconditional exec zsh blocks inside ~/.bashrc routinely exceed 10 seconds and trigger LS_START_FAILED. Guard non-interactive startup scripts cleanly in your remote dotfiles:

# Place at the top of ~/.bashrc or ~/.zshrc on remote SSH devboxes
if [ "${ANTIGRAVITY_RESOLVING_ENVIRONMENT:-0}" = "1" ]; then
  return
fi

# Only upgrade bash to zsh for real interactive TTY sessions
if [ -t 0 ] && [ -x /usr/bin/zsh ] && [ -z "$ZSH_VERSION" ]; then
  exec /usr/bin/zsh -l
fi

How Do You Sync Antigravity Skills Into Docker Dev Containers?

You persist Google Antigravity skills inside Docker dev containers by committing project workflows to .agents/skills/ inside the repo and bind-mounting your host ~/.gemini/config/skills/ directory via devcontainer.json. Because Docker containers discard writable container layers on rebuild, any skills authored interactively inside a container vanish unless backed by a persistent mount or cloud skill manager.

Per the Dev Container metadata reference, the mounts property accepts Docker --mount syntax using type: "bind" or named volumes, while forwardPorts ensures localhost services inside the container bind immediately upon attach. Pairing a Debian Bookworm (glibc 2.36) container image with an explicit read-write bind mount for ~/.gemini/config/skills lets Antigravity, Codex CLI, and Claude Code share skills across rebuilds without copying files manually.

// .devcontainer/devcontainer.json — glibc image + persistent Antigravity skill mount
{
  "name": "backend-glibc-devbox",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20-bookworm",
  "remoteUser": "node",
  "mounts": [
    {
      "source": "${localEnv:HOME}/.gemini/config/skills",
      "target": "/home/node/.gemini/config/skills",
      "type": "bind"
    },
    {
      "source": "${localEnv:HOME}/.agents/skills",
      "target": "/home/node/.agents/skills",
      "type": "bind"
    }
  ],
  "forwardPorts": [3000, 8080],
  "postCreateCommand": "mkdir -p /home/node/.gemini/config/skills"
}

Remember two container-specific boundaries when using bind mounts over a remote SSH host. First, if the remote SSH daemon runs on Linux and your container runs on that same Linux host, ${localEnv:HOME} resolves on the host running the container daemon—so the host still needs your up-to-date skills before mounting, and host-container UID mismatches must be resolved to avoid Linux inotify and EACCES file watcher errors. Second, adhere strictly to the Agent Skills open specification—keeping each skill’s name under 64 lowercase hyphenated characters and description under 1,024 characters—so the exact same mounted folder loads cleanly across Antigravity, OpenAI Codex CLI, and Claude Code. For sidecar security boundaries inside shared worktrees, review Google Antigravity sidecars and tool execution policies.

The Sprawl Moment: Losing Global Skills Across SSH Boxes and Ephemeral Containers

You spend three weeks refining 18 global skills and custom MCP configurations on your MacBook Pro—covering Terraform drift checks, database migration audits, and strict TypeScript PR reviews. On Thursday morning, a GPU-heavy integration test forces you to connect Antigravity over SSH to a fresh Ubuntu cloud devbox and attach to a Debian dev container. The moment the remote session opens, every slash command and personal workflow disappears: ~/.gemini/config/skills/ on the cloud box is completely empty, your container has no access to your Mac’s ~/.claude/skills/ or Cursor rules, and you spend 40 minutes hunting through old Slack threads and GitHub gists to reconstruct two critical review prompts. Worse, after patching one of those skills directly inside the remote container to fix a schema bug, an image rebuild wipes the container layer Friday afternoon—leaving your MacBook, your SSH host, and your Cursor workspace running three contradictory versions of the same workflow.

How Do You Keep One Skill Library Synced Across Remote Devboxes and Mac?

You eliminate remote devbox and container drift by decoupling your canonical skill library from ephemeral local disks and syncing skills centrally over cloud sync and Model Context Protocol (MCP). Instead of using scp, brittle rsync cron jobs, or manual dotfiles commits every time a cloud VM is provisioned, a centralized manager keeps every surface aligned automatically.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

  • Connect Remote Agents Over MCP With Write Access: Any Antigravity session running on a remote SSH host or inside a Docker container can connect to your Prompttly library over MCP, retrieving and updating skills dynamically even on ephemeral cloud hosts with zero bind mounts.
  • Two-Way Local Sync on Mac: Prompttly compiles and syncs your library into real local skill folders for Claude Code and Codex, while keeping version history intact across every edit.
  • Instant Mac Hotkey Palette Across Terminal & SSH Windows: When driving a remote SSH terminal or an Antigravity (SSH: host) window from macOS, hit the global Prompttly hotkey to search and insert any prompt or skill into the active pane without copy-pasting.
  • Browser // Commands for Web Workflows: Invoke the exact same library inside ChatGPT and Claude using // shortcuts or save new snippets from documentation pages with the Chrome extension.

To compare how Antigravity’s remote worktrees stack up against OpenAI’s terminal sandbox, read our breakdown of Google Antigravity vs Codex CLI workspace architectures. If you also manage dotfiles across macOS, Linux, and Windows machines, follow our guide to moving AI coding agent skills across operating systems and building one reusable cross-agent skill library.

Frequently Asked Questions About Antigravity Remote SSH Workspaces

Where does Google Antigravity store skills and MCP configs on a remote SSH host?

When connected via Connect over SSH, Google Antigravity loads global skills, rules, hooks, MCP servers, and plugins from ~/.gemini/ on the remote Linux host (specifically ~/.gemini/config/skills/<skill-folder>/) and workspace skills from <workspace-root>/.agents/skills/ on the remote filesystem.

Can Google Antigravity Connect over SSH run inside an Alpine Linux Docker container?

No. Google Antigravity remote SSH servers require 64-bit Linux (x86_64 or arm64) with glibc 2.26 or newer, such as Ubuntu 18.04+, Debian 10+, or RHEL 8+. Containers built on Alpine Linux use musl libc and trigger the UNSUPPORTED_HOST error when Antigravity attempts to bootstrap ~/.antigravity-hub-server/.

Do Antigravity agents keep running if I close my MacBook over SSH?

Yes. Closing the Antigravity SSH window or putting your local laptop to sleep disconnects the OpenSSH tunnel while leaving the remote ~/.antigravity-hub-server/ process, Git worktrees, and active agents running on the Linux host until you explicitly trigger Stop SSH Server.

Why does Antigravity override ControlMaster and ForwardAgent in my SSH config?

Google Antigravity explicitly passes ForwardAgent=no, ForwardX11=no, ControlMaster=no, ControlPath=none, RemoteCommand=none, ServerAliveInterval=15, and ServerAliveCountMax=3 on its OpenSSH command line to guarantee deterministic tunnel isolation, prevent stalled multiplexed sockets, and detect dropped connections within 45 seconds.

How do I stop losing skills when rebuilding remote Docker dev containers?

Commit repository-specific skills to .agents/skills/ in Git, bind-mount ~/.gemini/config/skills from the host inside devcontainer.json, or synchronize your library through Prompttly over MCP so rebuilt containers immediately pull your latest skills and prompts.

Explore the full directory of agent workflow guides on the Prompttly Resources Hub, or test your next portable SKILL.md manifest with our free Claude Skill Creator:

Keep your Antigravity skills synced across every remote devbox

Stop rebuilding ~/.gemini/config/skills/ every time you spin up a cloud instance or container. Sync one library across Google Antigravity, Claude Code, Codex, and your Mac hotkey palette.