It was early evening, and I had just connected Zed to the Linux build box I use for my indie developer projects. I opened a new Antigravity thread in the agent panel. The status said it was signing in. It kept saying that. Nothing opened in the browser on my iMac.
In an SSH terminal on the same machine, agy worked perfectly. Same box, same account — only the editor path was locked out. I spent a good fifteen minutes staring at that mismatch before it made sense.
The problem wasn't a typo in my settings. It was a question of where and in what order the sign-in should happen. If you're stuck at the same spot, here's the path I'd walk you through, starting with how to recognize it.
First, tell the two failures apart
When Antigravity won't work in a remote Zed session, the symptom usually falls into one of two buckets, and they're fixed in completely different places.
| What you see | Where it's stuck | Where to look first |
|---|---|---|
| The panel waits on sign-in forever; the log shows "Credentials missing or invalid. Launching browser login flow..." | Authentication (OAuth browser hand-off) | This article |
| Requests fail with "Authentication required" (code -32000) | Authentication (no cached credentials) | This article |
| "Server exited with status exit status: 255" right after opening the panel | Startup (the process itself is dying) | The agy path and how the host resolves your user |
The exit 255 case has been reported on cloud Linux hosts that use OS Login, and no amount of sign-in work will fix it. It's worth ruling out before you go further.
If you're in one of the first two rows, the steps below apply directly.
Why it never comes back over SSH
In a remote session, Zed launches agy acp as a subprocess on the remote machine. With no credentials available, agy acp tries to open a browser for OAuth.
But the machine trying to open that browser is the server. On a headless box there's no browser to open, and even if there were, I'd never see it from my desk. What's left is a process waiting for a sign-in that can't finish, and a panel that waits right along with it.
The interactive agy was fine because it detects the remote environment and switches to a manual flow: it prints a URL and asks you to paste back a code. agy acp, running behind the editor, has no place to hold that conversation.
So the reliable fix is this: sign in where a human is actually looking at a screen, and let the editor reuse the result. The official ACP guide is written on the same assumption — agy acp reuses credentials cached by an interactive session.
The fix: run agy acp --login once on the remote machine
This takes a minute. Do it from a regular terminal, not from inside Zed.
- SSH into the remote machine.
- Check that
agy acp --helpworks. If it doesn't, your version predates ACP. - Run
agy acp --login. Open the printed URL in your local browser, sign in, and paste the code it gives you back into the terminal. - In Zed, start a fresh Antigravity thread in the agent panel.
The --login flag signs you in and exits, and the docs say explicitly that it works over SSH. Signing in once with an interactive agy session gets you to the same place.
While you're there, a small change to Zed's settings gives you a better clue the next time things stall:
{
"agent_servers": {
"Antigravity": {
"type": "custom",
"command": "/home/YOUR_USER/.local/bin/agy",
"args": ["acp", "--log-file", "/tmp/agy-acp-zed.log"]
}
}
}I use an absolute path for command because processes launched by an editor don't always see your login shell's PATH. Replace it with whatever which agy prints on the remote box. --log-file simply puts the server log somewhere you chose yourself.
Verify: a small check script for the remote side
Even after it works, expired credentials or a version swap can bring the same symptom back. I wanted to check things in the same order every time, so I keep this script on the remote machine.
What it solves: in one run, it tells you whether agy is found, whether it includes ACP, and whether the latest log shows an auth failure — then prints a single next step.
#!/usr/bin/env bash
# acp-auth-check.sh — run on the SSH host when Zed can't get into agy acp
set -u
AGY="$(command -v agy || true)"
if [ -z "$AGY" ]; then
echo "NG: agy is not on PATH. Find the install location and put the absolute path in Zed's command"
exit 1
fi
echo "OK: agy = $AGY"
if ! "$AGY" acp --help >/dev/null 2>&1; then
echo "NG: this agy build has no ACP support. Update it and try again"
exit 1
fi
echo "OK: agy acp is available"
# Pick the newest log from both the default location and the one set in Zed
LATEST="$(ls -t "$HOME"/.gemini/antigravity-cli/log/acp-*.log /tmp/agy-acp-zed.log 2>/dev/null | head -1)"
if [ -z "$LATEST" ]; then
echo "INFO: no ACP log yet. Open a thread in Zed once, then run this again"
exit 0
fi
echo "INFO: latest log = $LATEST"
if grep -qE 'Launching browser login flow|Authentication required|-32000' "$LATEST"; then
echo "NEXT: no credentials. Run 'agy acp --login' in this terminal, then reopen the Zed thread"
elif grep -qE 'exit status: 255|exited with status' "$LATEST"; then
echo "NEXT: this is a startup failure, not auth. Check how the host resolves your user (OS Login, etc.)"
else
echo "OK: no auth failure in the latest log"
fiA word on why it's written this way. It matches log strings because the panel never tells you more than "waiting." And it deliberately doesn't echo log contents to the screen — OAuth URLs and callbacks carry authorization data, short-lived as it is, and I wanted output I could safely show someone else.
If it still won't connect
If you're still stuck after agy acp --login, here's the order I'd try:
- See whether ACP's terminal login is offered. The official auth table lists a
terminal-loginmethod that uses a pasted code and works over SSH. It only appears in clients that support ACP terminal authentication, so depending on your Zed version, you may not see it. - Get in temporarily with an API key. Passing
GEMINI_API_KEYthroughenvin Zed's settings skips the browser entirely. Settings files are plain text and tend to get synced, so don't share one with a key in it — exporting the variable in the environment that launches Zed is safer. If you pay for Antigravity through your Google account, keep in mind that the quota you draw on may differ. - Compare your log with the existing forum thread. Google-account OAuth hanging in Zed over SSH has been reported as a bug where ACP doesn't reuse the CLI's credentials. Checking that your log shows the same wording before you post makes the conversation much shorter.
Someone on the forum also reported finishing the flow by copying the 127.0.0.1 callback URL from their local browser and feeding it to curl on the remote box. It may work, but hand-carrying authorization codes is easy to get wrong, so my own line is: if I've come this far, I switch to an API key.
Where I draw the line
For those first fifteen minutes, I kept re-checking the editor config — the spelling of args, the value of type, restarting Zed. All correct, none of it relevant.
Looking back, the editor's job is to launch the agent and relay the conversation. Signing in on my behalf was never part of that job.
I handle the sign-in at the screen; the editor handles launch and relay. Since I started thinking of it that way, running agy acp --login has become the first thing I do on any new remote host.
The same thinking helps when you pick where a Remote Control daemon should live. I wrote up how I decide which machine holds credentials in choosing a Remote Control host and shutting the daemon down cleanly.
For now, run agy acp --login once on the SSH host you're connected to, and reopen the Zed thread. If that gets you in, drop the check script on the same machine — the next time it stalls, you'll thank yourself.