Antigravity Server

通往你自己的 Antigravity 的第二道门。
修好移动端网页界面，界面流量不经 Google 中继，并在廉价 Linux 机器上无人值守运行。

官方远程	同一台服务器，经 `agy-server`

项目上没有 `+`，对话上没有 `⋮`。	每个项目可新建对话，每一行可删除 / 重命名 / 置顶 / 归档。

_{一台无头 Linux 机器，两道门，前后相隔几分钟拍摄。}

English · 한국어 · 日本語 · Português · Español

为什么选择 Antigravity Server？（对比官方远程桥接）

Google 现已在 antigravity.google.com 推出官方远程桥接：用同一账号登录，即可访问你所有正在运行 Antigravity 且开启远程访问的机器。“用手机访问自己的智能体”本身已不再需要本项目提供，而且无头 Linux 服务器同样会出现在那个列表里。

官方桥接下发到手机上的，是原封不动的桌面网页包。这正是 agy-server 的价值所在：它作为第二道直连门户站在同一个 Antigravity 内核前面，在网页包发出的路上把它改写成触屏能用的样子。

两者并不互斥。agy-server 打开的也只是官方桥接所用的那个 remoteControlEnabled 设置，因此同一台机器可以同时服务两边——用哪个地址都行。

	官方远程（`antigravity.google.com`）	Antigravity Server (`agy-server`)
移动端网页界面	原样的桌面网页包	面向触屏的 25 个运行时补丁
对话管理	移动端无法删除、置顶或归档	在 kebab 菜单与标题栏中删除、重命名、置顶、归档
项目导航	缺少项目 `(+)` 按钮；需在底部输入框切换	在项目列表顶部恢复 `(+)` 按钮
消息操作	撤销与复制藏在鼠标悬停之后	触屏上常显撤销（`↶`）与复制（`📋`）
iOS 键盘与输入	底部 Safe Area 留白，聚焦时视口抖动；换行触发输入法组合错乱	导航栏固定、安全区收起、对话高度自适应、问题模态框交互稳定，并保护回车时的 CJK 输入法组合状态与安全换行
文件上传	1MB RPC 文本大小限制	面向大体积日志、HAR、数据集的分块流式上传器
连接路径	经 Google 服务器中继	直连——你自己的域名、局域网或 VPN
服务器重启 / 断开连接	服务器重启导致 CSRF Token 失效，连接永久中断，必须手动刷新页面	无刷新自动重连 — 持久化 CSRF Token 与 gRPC status 14 转换，服务器重启后即刻自动恢复
内存维护	长时间运行内存无限制累积（~4GB+）	每日空闲重启 — 不打断工作流程，在空闲时自动重启语言服务器重置内存至约 450MB
无 Google 账号也能访问	不行 —— 账号即门禁	你自己的密码（PBKDF2）、会话与限流

快速开始

方案 1：Linux 服务器 / 云 VPS（推荐）

在无头 Linux 实例（Oracle Cloud 免费层、AWS、DigitalOcean 或家庭服务器）上运行：

curl -fsSL https://raw.githubusercontent.com/AFSlayer/antigravity-server/main/scripts/install.sh | bash

安装脚本执行过程：

提示输入您的域名（如 agy.example.com）和工作区路径。
直接从 Google 官方构建存储桶（storage.googleapis.com）下载 language_server 二进制文件（不重新分发 Google 专有文件）。
配置 Caddy 自动申请 HTTPS 证书、注册 systemd 服务并设置访问密码。

Google 账号认证

首次访问服务器时：

Web 界面直接登录：在浏览器中打开 Web UI，进入**设置（Settings）**菜单直接完成 Google 登录。
复制现有 Token（可选）：如果已在本地电脑登录过，可直接复制 Token 跳过认证：
```
scp ~/.gemini/jetski-standalone-oauth-token user@your-server:~/.gemini/
```

方案 2：桌面伴侣模式（macOS、Windows、Linux 桌面）

将本地电脑上运行的 Antigravity 共享给同一局域网下的手机：

# macOS & Linux
curl -fsSL https://raw.githubusercontent.com/AFSlayer/antigravity-server/main/scripts/install-desktop.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/AFSlayer/antigravity-server/main/scripts/install-desktop.ps1 | iex

agy-server 将打开包含二维码的本地控制面板。使用同一 Wi-Fi 下的手机扫描二维码即可免密直连。

移动端 PWA 设置（添加到主屏幕）

Antigravity Server 支持渐进式 Web 应用（PWA）标准。将其添加到移动设备主屏幕，即可在无地址栏和底部工具栏的全屏独立模式下运行：

iOS (Safari)：点击底部的分享按钮（⎋） → 选择添加到主屏幕（Add to Home Screen）。
Android (Chrome)：点击右上角菜单（⋮） → 选择安装应用或添加到主屏幕。

Tip

从主屏幕图标启动可确保虚拟键盘弹出时界面不抖动，并完美激活 0px 键盘紧贴补丁。

核心特性

⚡ 移动端专属 UX 补丁

触控便捷操作：在消息气泡上常驻显示撤销（↶）和复制（📋）按钮。
完整的对话管理：通过顶栏菜单删除对话，在列表菜单中一键置顶或归档。
精确虚拟键盘跟踪：输入法激活时固定顶部导航栏，自动将 Safe Area 间距压缩至 0px 并自适应对话高度。
平滑滚动锚定与顶部防护：解决长对话向上滚动查看历史记录时触发的无休止级联请求风暴，并稳定保持滚动定位。

📁 分块流式大文件上传

解除官方 Antigravity 的 1MB RPC 限制，将大体积日志或数据集直接流式上传至工作区：

🖥️ 桌面与平板电脑 Web 界面

除了移动端外，在笔记本或台式电脑的现代浏览器中同样拥有出色体验：

🔄 零停机无缝自动更新与每日内存维护

在无头 Linux 服务器上，agy-server 内置后台自动更新服务：

每日检查 Google 官方发布存储桶中的最新 language_server 版本。
以零停机的原子方式安全替换核心二进制文件。
每日空闲重启（Daily Idle Restart）：处于最新版本时，在无活动流且 15 分钟以上无请求的空闲窗口安全重启语言服务器，回收长会话累积的内存。若检测到活跃流量，将安全延迟 10 分钟重试。
手动检查与更新：运行 agy-server update。

🔁 无刷新自动重连与会话持久化

当语言服务器重启（如自动更新或服务重启）或网络短时间断开时：

CSRF Token 持久化：重启后继续复用相同的认证 Token，彻底防止因会话失效导致的拒绝连接。
gRPC-Web 协议转换：在后端暂时不可用期间返回标准 grpc-status: 14（Unavailable）而非 HTTP 502 HTML，保障前端原生状态流在服务就绪后数秒内自动恢复，无需手动刷新网页。
重连后断开警告横幅自动关闭：服务器重新连接成功后，自动检测并关闭输入框下方残留的“Lost connection”警告横幅。
加载转圈卡死自动恢复：针对移动端 WebKit 在 HTTP/2 复用流上的挂起现象，若网络空闲且加载超过 30 秒，客户端看门狗将自动安全刷新恢复连接。

📝 Web UI 内置规则与技能编辑器

无需通过终端连接服务器，直接在 Web 浏览器中编辑 Agent 指令（~/.gemini/GEMINI.md、~/.gemini/config/skills/）和项目规则：

前往 Settings → Customizations 菜单。
点击规则或技能旁的 Edit 按钮展开内联编辑器。
修改后点击 Save，更改将以原子方式保存至主机文件系统并即时生效。

生产环境反向代理配置（Caddy / Nginx）

为了支持智能体的实时流式输出（SSE）、WebSocket 通信及大文件上传，反向代理需禁用缓冲并配置 WebSocket 升级：

Caddy

agy.example.com {
    encode zstd gzip

    reverse_proxy 127.0.0.1:8765 {
        flush_interval -1
    }
}

Nginx

server {
    listen 443 ssl http2;
    server_name agy.example.com;

    # 允许大体积流式上传
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;

        # WebSocket 支持
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 禁用缓冲以实现实时流式输出（必须）
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;

        # 传递真实客户端 IP
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Important

在反向代理后运行时，请配置 --trusted-proxies 127.0.0.1/32（或设置环境变量 AGY_TRUSTED_PROXIES=127.0.0.1/32），以确保防暴力破解系统能准确获取真实访客 IP。

工作原理

Antigravity 内部包含名为 language_server 的独立二进制程序。使用 --standalone 运行时，它在本地 127.0.0.1 提供 Web 界面。

agy-server 作为其前端反向代理，负责身份认证、动态运行时补丁注入及流式文件上传。

移动端 UX 补丁详情

无论是官方远程桥接还是通过 agy-server，Antigravity 提供的 Web 资源包均为桌面版本。agy-server 通过 internal/patches/registry.go 中的补丁在运行时动态重写资源包。注册表中包含 45 项补丁，其中 25 项专为触控移动端优化，其余涵盖文件上传、导航、登录及缓存刷新。精选补丁对照：

分类	桌面端原生行为	agy-server 补丁优化行为
导航栏	移动端屏幕隐藏项目旁的新建 `(+)` 按钮	在每个项目行右侧恢复 `(+)` 新建对话按钮
对话管理	触控设备无法删除、置顶或归档对话	在 `⋮` 菜单和标题栏中补全删除、置顶 (Pin) 与归档 (Archive) 功能
消息操作	撤销与复制按钮仅在鼠标悬停时显示	在触控设备上常驻显示撤销（`↶`）和复制（`📋`）按钮
虚拟键盘与滚动	iOS Safari 视口抖动、底部留白，长对话向上滚动时触发雪崩式重复请求	实时跟踪 visualViewport 偏移，折叠 Safe Area 为 0px，锁定对话布局，启用 CSS 滚动锚定并添加顶部滚动守卫阻断级联请求
文件上传	1MB RPC 负载上限导致日志与数据集上传失败	通过分块流式上传端点直接异步写入磁盘
触控响应	存在 300ms 点击延迟与双击缩放	设置 `touch-action: manipulation` 实现零延迟触控响应
连接稳定性与横幅	重连成功后“Lost connection”横幅仍持续显示，或移动端 WebKit 在 HTTP/2 复用流上挂起	检测到服务器心跳正常后自动清除断联横幅，若在网络空闲状态下加载转圈卡死超过 30 秒则由看门狗自动安全重连
输入行为	移动端回车直接发送或破坏输入法未上屏状态；存在斜杠命令/标签时跳行异常	保持原生换行，保护输入法组合状态，修复含斜杠命令时的 Cmd+Left(macOS)/Home(全平台) 行首导航与 Ctrl+Left 逐词导航，通过 Cmd/Ctrl+Enter 发送
模型选择	点击模型选项时下拉菜单立即自动关闭	点击时正常展开 reasoning effort 推理深度子菜单

运行 agy-server doctor 可检查当前安装的资源包中所有补丁的应用状态。

CLI 命令

agy-server                      以桌面伴侣模式启动（局域网）
agy-server serve                作为无头服务器守护进程运行
agy-server update               检查并升级 Google 官方 language_server
agy-server doctor               诊断补丁完整性与系统状态
agy-server passwd [password]    设置或更改 Web 访问密码
agy-server sessions [revoke]    查看活跃会话或注销所有设备
agy-server config [flags]       管理 config.json 配置项

安全性

密码保护：密码使用 PBKDF2-SHA256（200,000 次哈希迭代）加密存储。
会话令牌：256 位密码学安全随机令牌；磁盘上仅存储其 SHA-256 哈希值。
CSRF Token 持久化与规范化：以仅所有者可见权限（0600）安全存储，并通过代理透明规范化注入，保障服务器重启后免于会话失效拒绝。
防暴力破解：连续登录失败 5 次将触发临时 IP 封禁（5 至 30 分钟）。
上传目录隔离：文件上传严格限制在配置的项目目录内；路径遍历攻击（../）将被立即拦截。
受信任代理：在 Nginx、Caddy 或 Cloudflare 之后部署时，请配置 --trusted-proxies 防止 Header 伪造。

许可证

Apache-2.0。与 Google 无隶属或背书关系。详见 DISCLAIMER.md。

FilesExpand file tree

README.zh-CN.md

Latest commit

History