Headless Mode for Servers - Antigravity Manager

Overview

Headless mode allows Antigravity Manager to run on servers without a graphical desktop environment. It provides full functionality through a Web-based interface and API endpoints.

Headless mode is automatically enabled when using Docker or running with the --headless flag.

Headless vs Desktop Mode

Headless Mode

Web-based management UI
API-first design
No GUI dependencies
Perfect for servers/containers
Lower resource usage

Desktop Mode

Native desktop application
System tray integration
Tauri-based GUI
Local OAuth callbacks
Auto-update support

Running Headless Mode

Direct Binary Execution

# Download or build the binary
./antigravity-tools --headless

With Environment Variables

export API_KEY="sk-your-secure-key"
export WEB_PASSWORD="admin-password"
export LOG_LEVEL="info"
export PORT="8045"

./antigravity-tools --headless

Systemd Service (Linux)

Create a systemd service for automatic startup:

/etc/systemd/system/antigravity-manager.service

[Unit]
Description=Antigravity Manager Headless Service
After=network.target

[Service]
Type=simple
User=antigravity
WorkingDirectory=/opt/antigravity
ExecStart=/opt/antigravity/antigravity-tools --headless

# Environment variables
Environment="API_KEY=sk-your-secure-key"
Environment="WEB_PASSWORD=your-admin-password"
Environment="LOG_LEVEL=info"
Environment="ABV_BIND_LOCAL_ONLY=false"

# Security
NoNewPrivileges=true
PrivateTmp=true

# Restart policy
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable antigravity-manager
sudo systemctl start antigravity-manager
sudo systemctl status antigravity-manager

Headless-Specific Configuration

Environment Variables

string

required

API key for authenticating API requests from AI clients.Also accepts: ABV_API_KEY

string

Password for Web UI login. If not set, uses API_KEY.Also accepts: ABV_WEB_PASSWORD

string

default:"AllExceptHealth"

Authentication mode in headless:

AllExceptHealth: Auth required except /health (default in headless)
Strict: Auth required for all endpoints
Off: No authentication (dangerous!)
Auto: Automatically determined

Also accepts: ABV_AUTH_MODE

boolean

default:"false"

true: Bind to 127.0.0.1 (localhost only)
false: Bind to 0.0.0.0 (all network interfaces)

In Docker/headless mode, defaults to false to allow LAN access.

integer

default:"8045"

Port for the Web UI and API endpoints.

integer

default:"104857600"

Maximum request body size (bytes). Default: 100MB for large image uploads.

string

default:"/app/dist"

Path to frontend static files. Pre-configured in Docker images.

string

Public URL for OAuth callbacks when behind reverse proxy.Example: https://antigravity.example.com

string

default:"info"

Logging verbosity: debug, info, warn, error

string

default:"info"

Rust-specific logging. Overrides LOG_LEVEL for Rust components.

Code Reference

Headless mode initialization is in src-tauri/src/lib.rs:109-289:

let args: Vec<String> = std::env::args().collect();
let is_headless = args.iter().any(|arg| arg == "--headless");

if is_headless {
    info!("Starting in HEADLESS mode...");
    // ... headless initialization
}

// API Key injection (lines 186-198)
let env_key = std::env::var("ABV_API_KEY")
    .or_else(|_| std::env::var("API_KEY"))
    .ok();

if let Some(key) = env_key {
    if !key.trim().is_empty() {
        info!("Using API Key from environment variable");
        config.proxy.api_key = key;
        modified = true;
    }
}

// Web password injection (lines 200-212)
let env_web_password = std::env::var("ABV_WEB_PASSWORD")
    .or_else(|_| std::env::var("WEB_PASSWORD"))
    .ok();

if let Some(pwd) = env_web_password {
    if !pwd.trim().is_empty() {
        info!("Using Web UI Password from environment variable");
        config.proxy.admin_password = Some(pwd);
        modified = true;
    }
}

// Headless defaults to LAN access (lines 166-176)
let bind_local_only = std::env::var("ABV_BIND_LOCAL_ONLY")
    .map(|v| matches!(v.to_lowercase().as_str(), "1" | "true" | "yes" | "on"))
    .unwrap_or(false);

if bind_local_only {
    config.proxy.allow_lan_access = false;
    modified = true;
} else {
    config.proxy.allow_lan_access = true;
}

Web UI Access

In headless mode, access the management interface at:

http://localhost:8045

Or from another device on the network (if ABV_BIND_LOCAL_ONLY=false):

http://192.168.1.100:8045

Web UI Features

Account Management

Add, edit, and remove Google accounts via OAuth flow

Quota Monitoring

Real-time quota tracking and account health status

API Configuration

Configure proxy settings, model routing, and API keys

Logs and Monitoring

View API request logs, token usage, and system status

Settings

Configure security, IP whitelisting, and advanced options

Security Considerations

Headless mode forces auth_mode to AllExceptHealth if it was Off or Auto.

Authentication Flow

Web UI Login: Uses WEB_PASSWORD (or API_KEY if not set)
API Requests: Use API_KEY in Authorization header
Health Endpoint: Always accessible at /health (no auth)

Firewall Configuration

# Allow port 8045 from specific IP
sudo ufw allow from 192.168.1.0/24 to any port 8045

# Or allow from anywhere (less secure)
sudo ufw allow 8045

# Allow port 8045
sudo firewall-cmd --permanent --add-port=8045/tcp
sudo firewall-cmd --reload

# Allow port 8045
sudo iptables -A INPUT -p tcp --dport 8045 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

Logging and Monitoring

Log Locations

Application Data: ~/.antigravity_tools/
Logs: ~/.antigravity_tools/logs/ (if configured)
Configuration: ~/.antigravity_tools/gui_config.json

View Logs

Systemd Service
Docker Container
Direct Execution

# Real-time logs
sudo journalctl -u antigravity-manager -f

# Last 100 lines
sudo journalctl -u antigravity-manager -n 100

# Since boot
sudo journalctl -u antigravity-manager -b

# Real-time logs
docker logs -f antigravity-manager

# Last 100 lines
docker logs --tail 100 antigravity-manager

# Since timestamp
docker logs --since 2026-03-03T10:00:00 antigravity-manager

# With debug logging
LOG_LEVEL=debug ./antigravity-tools --headless

# Or redirect to file
./antigravity-tools --headless 2>&1 | tee antigravity.log

Health Check Endpoint

curl http://localhost:8045/health

Response:

{
  "status": "ok",
  "version": "4.1.27"
}

Use this for monitoring tools like Prometheus, Uptime Kuma, or Nagios.

OAuth in Headless Mode

OAuth callbacks work in headless mode through the Web UI’s built-in OAuth handler.

Standard OAuth Flow

Access Web UI at http://your-server:8045
Navigate to Accounts → Add Account → OAuth
Copy the generated authorization URL
Open URL in any browser (can be on different device)
Complete Google OAuth authorization
Browser redirects to callback URL
Web UI automatically completes the flow

Behind Reverse Proxy

If behind a reverse proxy, set the public URL:

export ABV_PUBLIC_URL="https://antigravity.example.com"

This ensures OAuth callbacks redirect to your public domain instead of localhost:8045.

Headless-Specific Features

Automatic Admin Server

Headless mode automatically starts the admin server on port 8045 to serve the Web UI:

// From lib.rs:356-373
if let Ok(config) = modules::config::load_app_config() {
    // Ensure admin server is running
    if let Err(e) = commands::proxy::ensure_admin_server(
        config.proxy.clone(),
        &state,
        integration.clone(),
        Arc::new(cf_state.inner().clone()),
    ).await {
        error!("Failed to start admin server: {}", e);
    }
}

No Tray Icon

Headless mode automatically disables system tray:

let tray_enabled = should_enable_tray();
// Returns false in headless mode

Graceful Shutdown

Headless mode handles Ctrl+C for clean shutdown:

// Wait for Ctrl-C
tokio::signal::ctrl_c().await.ok();
info!("Headless mode shutting down");

Performance Tuning

Resource Limits

For systemd services:

/etc/systemd/system/antigravity-manager.service

[Service]
# Memory limit
MemoryLimit=1G

# CPU quota (50% of one core)
CPUQuota=50%

# Max open files
LimitNOFILE=4096

Concurrency Settings

Adjust in gui_config.json:

{
  "proxy": {
    "max_connections": 100,
    "request_timeout": 30,
    "max_retries": 3
  }
}

Troubleshooting

Cannot access Web UI from other devices

Check ABV_BIND_LOCAL_ONLY is false:

grep allow_lan_access ~/.antigravity_tools/gui_config.json

Verify firewall allows port 8045:
sudo netstat -tlnp | grep 8045
Test from server:
curl http://localhost:8045/health

OAuth callbacks fail

Ensure admin server is running:
curl http://localhost:8045
If behind reverse proxy, set ABV_PUBLIC_URL
Check firewall allows callback port

High CPU usage

Check for excessive logging:
export LOG_LEVEL=warn

Review background tasks in logs:

journalctl -u antigravity-manager | grep -i "background\|task\|scheduler"

Smart scheduler is disabled by default (v4.1.24+)

Service won't start

Check systemd status:

sudo systemctl status antigravity-manager

Review recent logs:

sudo journalctl -u antigravity-manager -n 50

Verify binary path and permissions:

ls -la /opt/antigravity/antigravity-tools

Next Steps

Reverse Proxy Setup

Add HTTPS and custom domain with Nginx or Caddy

API Integration

Connect Claude CLI, OpenCode, and other clients

Security Best Practices

Configure IP whitelisting, rate limiting, and authentication

Monitoring

Set up Prometheus, Grafana, or other monitoring tools

​Overview

​Headless vs Desktop Mode

Headless Mode

Desktop Mode

​Running Headless Mode

​Direct Binary Execution

​With Environment Variables

​Systemd Service (Linux)

​Headless-Specific Configuration

​Environment Variables

​Code Reference

​Web UI Access

​Web UI Features

​Security Considerations

​Authentication Flow

​Firewall Configuration

​Logging and Monitoring

​Log Locations

​View Logs

​Health Check Endpoint

​OAuth in Headless Mode

​Standard OAuth Flow

​Behind Reverse Proxy

​Headless-Specific Features

​Automatic Admin Server

​No Tray Icon

​Graceful Shutdown

​Performance Tuning

​Resource Limits

​Concurrency Settings

​Troubleshooting

​Next Steps

Reverse Proxy Setup

API Integration

Security Best Practices

Monitoring

Overview

Headless vs Desktop Mode

Running Headless Mode

Direct Binary Execution

With Environment Variables

Systemd Service (Linux)

Headless-Specific Configuration

Environment Variables

Code Reference

Web UI Access

Web UI Features

Security Considerations

Authentication Flow

Firewall Configuration

Logging and Monitoring

Log Locations

View Logs

Health Check Endpoint

OAuth in Headless Mode

Standard OAuth Flow

Behind Reverse Proxy

Headless-Specific Features

Automatic Admin Server

No Tray Icon

Graceful Shutdown

Performance Tuning

Resource Limits

Concurrency Settings

Troubleshooting

Next Steps