서버에서 Antigravity CLI(agy) 실행하기

2026년 6월 18일부터 Gemini CLI는 무료, Google AI Pro, Ultra 개인 계정을 지원하지 않습니다. Google의 발표는 이런 사용자를 Antigravity CLI, 즉 agy로 안내합니다. 서버에서 신경 써야 할 부분은 브라우저 없이 로그인하기, Google 로그인과 API 키 중 고르기, 그리고 아무도 터미널 앞에 없을 때 agy가 권한을 어떻게 처리하는지 아는 것입니다. 순서대로 살펴봅니다.

agy 설치하기

Linux나 macOS에서, 일반(root가 아닌) 사용자로 실행합니다.

curl -fsSL https://antigravity.google/cli/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"   # if ~/.local/bin isn't on PATH yet
command -v agy

공식 설치 페이지에 따르면 바이너리는 ~/.local/bin/agy에 설치되며, macOS, Linux, Windows를 지원합니다. 설치 프로그램은 플랫폼별 빌드를 받아 오며, Linux 빌드는 amd64와 arm64 모두 있으므로 ARM VPS도 괜찮습니다. 새 셸과 tmux 창에서도 쓰이도록 PATH 줄을 ~/.bashrc나 ~/.profile에 추가하세요.

서버에 맞는 습관 하나: agy는 백그라운드에서 스스로 업데이트합니다. 노트북에서는 편리하지만, 계속 켜 두는 머신에서는 긴 세션 도중에 버전이 바뀔 수 있다는 뜻입니다. Maude는 설치하는 버전을 고정하고 AGY_CLI_DISABLE_AUTO_UPDATE=1로 이를 끕니다. 같은 예측 가능성을 원한다면, agy를 시작하는 셸이나 유닛에서 이 변수를 export하세요.

SSH 로그인 흐름

SSH 세션에서 agy를 시작하고 Google 로그인을 고릅니다. 노트북이라면 브라우저가 열리겠지만, SSH에서는 원격 세션을 감지하고 대신 인증 URL을 출력합니다. 그다음은 이렇습니다.

1. URL을 복사해 휴대폰이나 노트북에서 엽니다.
2. Antigravity에 쓰는 Google 계정으로 로그인합니다.
3. 페이지가 주는 코드를 복사해 터미널에 붙여넣습니다.

자격 증명은 OS 키링(Linux에서는 Secret Service)에 저장됩니다. 맨 VPS에는 키링을 잠금 해제할 데스크톱 세션이 없습니다. agy 1.0.0에 대해 제기된 GitHub issue는 바로 그 때문에 헤드리스 Linux에서 로그인이 반복되는 문제와, 파일 대체 저장 방식의 시간대 버그를 보고합니다. 보고자의 우회 방법은 GEMINI_FORCE_FILE_STORAGE=true TZ=UTC agy …였습니다. 현재 버전에서도 필요한지는 확인하지 못했습니다. agy가 실행할 때마다 다시 로그인하라고 한다면 이 issue부터 살펴보세요. 그렇지 않다면 API 키 모드를 쓰세요.

로그아웃하고 저장된 프로필을 지우려면 agy 안에서 /logout을 실행합니다.

헤드리스용 API 키 모드

CI, 공용 머신, 또는 Google 세션을 남겨 두고 싶지 않은 서버에서는 Gemini API 키로 agy를 실행하세요. 설치 문서는 두 단계를 안내합니다. 먼저 ~/.gemini/antigravity-cli/settings.json에서 모델 제공자를 설정합니다. 파일이 이미 있다면 내용을 병합하세요.

{
  "modelProvider": "gemini"
}

그런 다음 프로세스가 키를 쓸 수 있게 합니다.

export GEMINI_API_KEY="…"   # e.g. in ~/.profile, or an EnvironmentFile for a systemd unit

이렇게 하면 계정 로그인을 완전히 건너뜁니다. 사용량은 Google AI 요금제에서 차감되지 않고 Gemini API 가격에 따라 토큰당 청구됩니다. 키가 셸 기록이나 에이전트가 작업하는 저장소에 남지 않도록 하세요.

아무도 보지 않을 때의 권한

서버에서 사람들을 가장 놀라게 하는 동작입니다. agy 1.2.14에서의 저희 테스트에서, 헤드리스 실행(agy -p … 또는 stream-json 모드)은 도구 실행 전에 멈춰서 물어볼 수 없습니다. 권한이 필요한 명령이나 파일 쓰기는 거부되고, 턴의 결과에 거부된 것으로 나열됩니다. 작업을 통과시키는 방법은 세 가지입니다.

• 허용 규칙. agy는 ~/.gemini/antigravity-cli/settings.json의 permissions.allow에서 규칙을 읽습니다. 항목은 "command(npm test)", "write_file(src/app.ts)", "command(*)" 같은 형태이며, 시작할 때 읽힙니다.
• 모드. --mode accept-edits는 파일 편집을 자동 승인하지만 명령은 여전히 거부됩니다. --mode plan은 실행하지 않고 계획만 세웁니다.
• 확인 없음. 버려도 되는 머신을 위한 --dangerously-skip-permissions입니다. 쓰기 전에 에이전트를 전체 권한으로 안전하게 실행하기를 읽어 보세요.

터미널의 대화형 agy와 아래의 Remote Control은 멈춰서 물어볼 수 있습니다. 따라서 이 제한은 스크립트로 실행하는 헤드리스 사용에만 해당합니다.

Gemini CLI 설정 가져오기

이전 가이드에서 다룹니다. 이미 Gemini CLI가 있던 서버라면 요점은 이렇습니다.

• 첫 실행 시 이전을 제안합니다. agy가 기존 Gemini CLI 설정을 찾으면, 변환할 확장 프로그램과 전역 설정의 체크리스트를 보여 줍니다.
• 확장 프로그램은 플러그인이 됩니다. 언제든 agy plugin import gemini를 실행하면 Gemini 확장 프로그램을 Antigravity 플러그인으로 변환합니다.
• 컨텍스트 파일은 그대로 작동합니다. GEMINI.md(워크스페이스와 ~/.gemini/GEMINI.md)와 AGENTS.md는 변경 없이 읽힙니다.
• MCP 서버는 약간의 수정이 필요합니다. 전역 서버는 ~/.gemini/config/mcp_config.json에, 워크스페이스 서버는 .agents/mcp_config.json에 둡니다. 기존의 url/httpUrl 키는 serverUrl로 이름을 바꾸세요.
• 스킬은 옮겨야 합니다. 워크스페이스 스킬은 .gemini/skills/에서 .agents/skills/로, 전역 스킬은 ~/.gemini/antigravity-cli/skills/로 갑니다. 직접 옮겨야 합니다.

Google은 아직 기능이 완전히 같지는 않다고 말하며, 이전 가이드에는 일부 사용자 지정 테마와 시각적 조정이 옮겨지지 않는다고 나와 있습니다. 워크플로가 특정 확장 프로그램에 의존한다면, 이전 설정을 지우기 전에 가져온 뒤 테스트하세요.

Remote Control 데몬 vs Maude

Google은 다른 기기에서 agy에 닿는 공식 방법을 제공합니다. Remote Control 문서에 따르면 세 가지 방법으로 시작할 수 있습니다.

• 실행 중인 세션 안에서 /remote-control. 해당 CLI 세션이 끝나면 터널도 끝납니다.
• 세션을 시작할 때 agy --remote-control. 이 터널도 세션이 끝나면 끝납니다.
• 헤드리스 데몬: agy remote-control start --name my-vps, 그리고 agy remote-control status와 agy remote-control stop. 백그라운드에서 계속 실행되는 OS 서비스로 등록됩니다.

같은 Google 계정으로 로그인한 아무 브라우저의 웹 대시보드에서 조작합니다. 문서에 따르면 대시보드를 휴대폰 홈 화면에 설치해 푸시 알림을 받을 수 있고, 권한 요청에는 터미널이나 원격 UI 어디서든 답할 수 있습니다. 계정이나 조직의 기능 플래그로 차단될 수 있다고도 나와 있습니다.

Antigravity만 쓰고 계정에서 기능 플래그가 켜져 있다면, 공식 데몬이 당연한 첫 선택입니다. 무료이고, 실행 전에 물어볼 수 있습니다.

휴대폰에서 실행하기

다른 에이전트와 함께 서버에서 agy를 실행하고 네이티브 앱으로 조작하고 싶다면 Maude가 선택지 중 하나입니다. 서버를 추가하면 앱이 검증된 버전의 agy를 설치하고, 휴대폰에서 로그인합니다. 코드를 붙여넣는 Google 로그인이나 Gemini API 키를 쓸 수 있습니다. Maude의 Antigravity에 대해 솔직히 말하자면, Maude는 헤드리스 agy를 조작하므로 도구 실행 전에 멈춰서 물어볼 수 없습니다. Maude는 거부된 작업을 보여 주고, 승인하면 허용 규칙을 추가해 다시 시도합니다. 자세한 내용은 Antigravity 에이전트 페이지에 있습니다. Gemini CLI 변경 자체와 사람들이 옮겨 간 다른 선택지는 Gemini CLI 종료에 관한 글에서 다룹니다.

자주 묻는 질문

변경 사항

• 2026년 10월 1일 — 최초 게시. 설치, 인증, 이전, Remote Control 관련 내용은 antigravity.google 문서로 확인했고, 헤드리스 권한 동작은 agy 1.2.14에서의 자체 테스트 결과입니다.