---
name: antigravity-remote-vm
description: >-
  Provisions and configures a Google Cloud Compute Engine (GCE) virtual machine
  to run the Antigravity CLI (agy) and its persistent remote-control daemon.
  Use when the user asks to create or set up a Compute Engine VM, cloud dev box,
  or remote host for Antigravity remote control.
---

# Antigravity Remote Control VM Setup

> [!WARNING]
> **Disclaimer**: This skill is not production code and should be reviewed before use. The thoughts and code expressed in this skill are those of the author, not the author's employer.

Use this workflow to provision a Google Cloud Compute Engine VM and configure it to run the Antigravity CLI (`agy`) remote-control daemon.

## Step 1: Confirm VM Specifications

If not already specified by the user, confirm:
- **Instance Name** (default: `antigravity-remote`)
- **Zone** (e.g., `us-west1-a`)
- **Machine Type** (default: `e2-medium` for CLI/remote-control; `e2-standard-4` for heavier workloads)
- **OS Image & Disk** (default: Debian 12 `debian-12` in `debian-cloud`, `50GB` `pd-balanced`)

## Step 2: Provision the Compute Engine VM

Validate syntax with `gcloud help compute instances create` if the `gcloud` skill is active, then create the VM:

```bash
gcloud compute instances create <INSTANCE_NAME> \
  --project=<PROJECT_ID> \
  --zone=<ZONE> \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --boot-disk-size=50GB \
  --boot-disk-type=pd-balanced \
  --quiet
```

## Step 3: Install `agy` and Configure Systemd Linger via IAP Tunnel

> [!IMPORTANT]
> **Avoid direct port-22 `scp` timeouts and large binary uploads**:
> 1. Many projects restrict port 22 ingress (`default-allow-ssh`) to Google Cloud IAP (`35.235.240.0/20`), causing standard `gcloud compute ssh/scp` without `--tunnel-through-iap` to hang and time out. Always include `--tunnel-through-iap`.
> 2. Do **not** `scp` the local `/usr/bin/agy` binary (~234 MB) over the tunnel. Instead, run the official installer (`https://antigravity.google/cli/install.sh`) directly on the remote VM.
> 3. Symlink `~/.local/bin/agy` to `/usr/local/bin/agy` so non-interactive SSH sessions find `agy` on `PATH`, and enable `loginctl enable-linger` so the background user service stays running after SSH logout.

```bash
gcloud compute ssh <INSTANCE_NAME> \
  --project=<PROJECT_ID> \
  --zone=<ZONE> \
  --tunnel-through-iap \
  --command="curl -fsSL https://antigravity.google/cli/install.sh | bash && sudo ln -sf \$HOME/.local/bin/agy /usr/local/bin/agy && sudo loginctl enable-linger \$USER && agy remote-control status || true" \
  --quiet
```

## Step 4: Hand Off Interactive Authentication & Daemon Start

Because `agy remote-control start` requires a one-time interactive OAuth sign-in in a TTY, provide the user with the exact command to run in their terminal:

```bash
gcloud compute ssh <INSTANCE_NAME> \
  --project=<PROJECT_ID> \
  --zone=<ZONE> \
  --tunnel-through-iap \
  -- -t "agy remote-control start --name <INSTANCE_NAME>"
```

And to check daemon status later:

```bash
gcloud compute ssh <INSTANCE_NAME> \
  --project=<PROJECT_ID> \
  --zone=<ZONE> \
  --tunnel-through-iap \
  --command="agy remote-control status"
```