Server Deployment: Docker noVNC vs Headless Xvfb (Selection & Operations)
You want to deploy Antigravity Tools on a NAS/server to run it as a long-term local API gateway: always online, health-checkable, upgradeable, backup-capable, and troubleshootable when issues arise—not just to "remotely open the GUI and take a look."
This lesson only covers two battle-tested approaches provided by the project: Docker (with noVNC) and Headless Xvfb (systemd-managed). All commands and default values follow the deployment files in the repository.
If you just want to "get it running once"
The installation lesson already covers Docker and Headless Xvfb entry commands. You can start with Getting Started: Installation & Upgrades, then come back here to complete the "operations loop."
What You'll Learn
- Choose the right deployment pattern: understand what Docker noVNC and Headless Xvfb each solve
- Run through a complete loop: deployment → sync account data → health check
/healthz→ view logs → backup - Make upgrades controllable: understand the difference between Docker's "auto-update on start" and Xvfb's
upgrade.sh
Your Current Struggles
- Your server has no desktop, but you can't do without OAuth/authorization operations that "require a browser"
- Running it once isn't enough—you want: automatic recovery after power loss, health check capability, and backup
- You're worried about exposing port 8045 to security risks but don't know where to start hardening
When to Use This
- NAS/home servers: want to open GUI in a browser to complete authorization (Docker/noVNC is hassle-free)
- Long-running servers: prefer systemd process management, log persistence, and scripted upgrades (Headless Xvfb feels more like "operations on a project")
What is "Server Deployment" Mode?
Server deployment means: instead of running Antigravity Tools on your local desktop, you run it on a machine that's always online, and expose the reverse proxy port (default 8045) as your external service entry. Its core isn't "remote GUI viewing"—it's establishing a stable operations loop: data persistence, health checks, logging, upgrades, and backups.
Core Approach
- First choose "the capability you lack most": if you lack browser authorization, pick Docker/noVNC; if you lack operational control, pick Headless Xvfb.
- Then "lock down your data": accounts and configuration live in
.antigravity_tools/—either use Docker volumes or fix it to/opt/antigravity/.antigravity_tools/. - Finally "build an operable loop": use
/healthzfor health checks, check logs first when troubleshooting, then decide whether to restart or upgrade.
Prerequisite: Set your security baseline first
If you're going to expose 8045 to your LAN or the public, first review Security & Privacy: auth_mode, allow_lan_access, and the 'Don't Leak Account Info' Design.
Quick Selection Guide: Docker vs Headless Xvfb
| What matters most | Recommended choice | Why |
|---|---|---|
| Need browser for OAuth/authorization | Docker (noVNC) | Container comes with Firefox ESR built-in, operate directly in browser (see deploy/docker/README.md) |
| Want systemd management/log persistence | Headless Xvfb | install script installs systemd service and appends logs to logs/app.log (see deploy/headless-xvfb/install.sh) |
| Want isolation and resource limits | Docker | Compose approach natively isolates and makes resource limits easier to configure (see deploy/docker/README.md) |
Follow Along
Step 1: First confirm where your "data directory" is
Why Deployment succeeds but "no accounts/configuration" essentially means the data directory wasn't brought over or persisted.
- Docker approach mounts data to
/home/antigravity/.antigravity_toolsinside the container (compose volume) - Headless Xvfb approach puts data in
/opt/antigravity/.antigravity_tools(and fixes write location viaHOME=$(pwd))
What you should see
- Docker:
docker volume lsshowsantigravity_data - Xvfb:
/opt/antigravity/.antigravity_tools/exists and containsaccounts/andgui_config.json
Step 2: Get Docker/noVNC running (for scenarios requiring browser authorization)
Why The Docker approach packages "virtual display + window manager + noVNC + application + browser" into a container, saving you from installing a bunch of graphical dependencies on your server.
Execute on your server:
cd deploy/docker
docker compose up -dOpen noVNC:
http://<server-ip>:6080/vnc_lite.htmlWhat you should see
docker compose psshows the container running- Browser can open the noVNC page
About noVNC ports (recommended to keep default)
deploy/docker/README.md mentions using NOVNC_PORT to customize the port, but in the current implementation start.sh launches websockify listening on the hardcoded port 6080. To change the port, you need to adjust both the docker-compose port mapping and the start.sh listen port.
To avoid configuration inconsistency, recommend using the default 6080 directly.
Step 3: Docker persistence, health checks, and backup
Why Container availability depends on two things: process health (is it still running) and data persistence (accounts survive restarts).
- Confirm persistence volume is mounted:
cd deploy/docker
docker compose ps- Backup volume (project README provides tar backup method):
docker run --rm -v antigravity_data:/data -v $(pwd):/backup alpine \
tar czf /backup/antigravity-backup.tar.gz /data- Container health check (Dockerfile has HEALTHCHECK):
docker inspect --format '{{json .State.Health}}' antigravity-manager | jqWhat you should see
.State.Health.Statusishealthy- Current directory generates
antigravity-backup.tar.gz
Step 4: One-click install Headless Xvfb (for scenarios wanting systemd operations)
Why Headless Xvfb isn't "pure backend mode"—it runs GUI programs on the server using a virtual display—but it trades that for a more familiar operations style: systemd, fixed directories, log persistence.
Execute on your server (one-click script provided by the project):
curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/headless-xvfb/install.sh | sudo bashWhat you should see
- Directory
/opt/antigravity/exists systemctl status antigravityshows service running
More stable approach: review script first
curl -O .../install.sh to download, read it first, then sudo bash install.sh.
Step 5: Sync local accounts to server (required for Xvfb approach)
Why Xvfb installation just gets the program running. To make the reverse proxy actually usable, you need to sync your existing accounts/configuration from your local machine to the server's data directory.
The project provides sync.sh, which automatically searches your data directory on your machine by priority (like ~/.antigravity_tools, ~/Library/Application Support/Antigravity Tools), then rsyncs to the server:
curl -O https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/headless-xvfb/sync.sh
chmod +x sync.sh
./sync.sh root@your-server /opt/antigravityWhat you should see
- Terminal output similar to:
Syncing: <local> -> root@your-server:/opt/antigravity/.antigravity_tools/ - Remote service attempts restart (script calls
systemctl restart antigravity)
Step 6: Health checks and troubleshooting (both approaches)
Why The first thing after deployment isn't "connect a client"—it's establishing an entry point for quickly judging health status.
- Health check (reverse proxy service provides
/healthz):
curl -i http://127.0.0.1:8045/healthz- View logs:
## Docker
cd deploy/docker
docker compose logs -f
## Headless Xvfb
tail -f /opt/antigravity/logs/app.logWhat you should see
/healthzreturns 200 (actual response body depends on implementation)- Logs show reverse proxy service startup information
Step 7: Upgrade strategy (don't treat "auto-update" as the only solution)
Why Upgrades are the most likely action to "upgrade your system to unusable." You need to know exactly what each approach's upgrade does.
- Docker: on container startup, attempts to pull latest
.debvia GitHub API and install (if rate-limited or network error, continues using cached version). - Headless Xvfb: uses
upgrade.shto pull latest AppImage, and rolls back to backup if restart fails.
Headless Xvfb upgrade command (from project README):
cd /opt/antigravity
sudo ./upgrade.shWhat you should see
- Output similar to:
Upgrading: v<current> -> v<latest> - Service remains active after upgrade (script calls
systemctl restart antigravityand checks status)
Pitfall Warnings
| Scenario | Common Error (❌) | Recommended Practice (✓) |
|---|---|---|
| Lost accounts/config | ❌ Only care about "getting program running" | ✓ First confirm .antigravity_tools/ is persisted (volume or /opt/antigravity) |
| noVNC port change doesn't take effect | ❌ Only change NOVNC_PORT | ✓ Keep default 6080; to change, also verify websockify port in start.sh |
| Exposing 8045 to public | ❌ Don't set api_key/don't review auth_mode | ✓ First follow Security & Privacy for baseline, then consider tunnel/reverse proxy |
Lesson Summary
- Docker/noVNC solves the "server has no browser/desktop but needs authorization" problem, suitable for NAS scenarios
- Headless Xvfb feels more like standard operations: fixed directories, systemd management, scripted upgrades/rollbacks
- Whatever approach, get the loop right first: data → health check → logs → backup → upgrade
Recommended Next Steps
- You want to expose service to LAN/public: Security & Privacy: auth_mode, allow_lan_access
- Encountered 401 after deployment: 401/Auth Failure: auth_mode, Header Compatibility, and Client Configuration Checklist
- You want to expose service via tunnel: Cloudflared One-Click Tunnel
Appendix: Source Code Reference
Click to expand source code locations
Last updated: 2026-01-23
| Feature | File Path | Lines |
|---|---|---|
| Docker deployment entry and noVNC URL | deploy/docker/README.md | 5-13 |
| Docker deployment environment variable description (VNC_PASSWORD/RESOLUTION/NOVNC_PORT) | deploy/docker/README.md | 32-39 |
| Docker compose port mapping and data volume (antigravity_data) | deploy/docker/docker-compose.yml | 1-21 |
| --- | --- | --- |
| Docker startup script: launch Xtigervnc/Openbox/noVNC/application | deploy/docker/start.sh | 60-78 |
| Docker health check: confirm Xtigervnc/websockify/antigravity_tools processes exist | deploy/docker/Dockerfile | 60-79 |
| Headless Xvfb: directory structure and operations commands (systemctl/healthz) | deploy/headless-xvfb/README.md | 19-78 |
| Headless Xvfb: install.sh installs dependencies and initializes gui_config.json (default 8045) | deploy/headless-xvfb/install.sh | 16-67 |
| Headless Xvfb: sync.sh automatically discovers local data directory and rsyncs to server | deploy/headless-xvfb/sync.sh | 8-32 |
| Headless Xvfb: upgrade.sh downloads new version and rolls back on failure | deploy/headless-xvfb/upgrade.sh | 11-51 |
Reverse proxy service health check endpoint /healthz | src-tauri/src/proxy/server.rs | 120-194 |