Security Settings

Configure API keys, authentication, and security monitoring

Overview

Antigravity Manager provides comprehensive security features including API key management, IP filtering, and request authentication.

API Key Configuration

Primary API Key

api_key · string · required

Primary API key for proxy authentication

Format: Must start with sk- followed by UUID
Auto-generated: On first launch
Example: sk-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Location: config.rs:481

Never commit API keys to version control. Store them securely and rotate regularly.

Admin Password

admin_password · string

Separate password for Web UI management console

If not set, the API key is used for Web UI authentication.

Minimum Length: 4 characters
Use Case: Docker/browser environments where API key should not be exposed

Location: config.rs:484

Key Generation

API keys are automatically generated using UUID v4:

api_key: format!("sk-{}", uuid::Uuid::new_v4().simple())

Location: config.rs:576

Authentication Modes

auth_mode · enum · default: "auto"

Request authentication policy

Location: config.rs:146-157

Mode Options

auth_mode.off · value

No authentication required

Use Case: Local-only development Security Level: ⚠️ Low

auth_mode.strict · value

Authentication required for ALL routes

Use Case: Production environments with LAN access Security Level: ✅ High

auth_mode.all_except_health · value

Authentication required except /healthz endpoint

Use Case: Production with health monitoring Security Level: ✅ High

auth_mode.auto · value

Recommended automatic mode

Behavior:

• LAN access enabled → all_except_health
• Local only → off

Use Case: Most deployments Security Level: ⚡ Adaptive

Location: security.rs:25-36

IP Access Control

Blacklist Configuration

security_monitor.blacklist.enabled · boolean · default: "false"

Enable IP blacklist filtering

Location: config.rs:395

security_monitor.blacklist.block_message · string · default: "Access denied"

Custom message shown to blocked IPs

Location: config.rs:398-399

Whitelist Configuration

security_monitor.whitelist.enabled · boolean · default: "false"

Enable whitelist-only mode

When enabled, only whitelisted IPs can access the service.

Location: config.rs:420

security_monitor.whitelist.whitelist_priority · boolean · default: "true"

Whitelist IPs bypass blacklist checks

If true, whitelisted IPs are never blocked even if in blacklist.

Location: config.rs:423

Configuration Example

{
  "proxy": {
    "security_monitor": {
      "blacklist": {
        "enabled": true,
        "block_message": "Your IP has been blocked. Contact support."
      },
      "whitelist": {
        "enabled": true,
        "whitelist_priority": true
      }
    }
  }
}

Network Security

Bind Address Control

allow_lan_access · boolean · default: "false"

Control network exposure

false (default):

• Bind to 127.0.0.1
• Local machine only
• Privacy-first approach

true:

• Bind to 0.0.0.0
• Allow LAN access
• Requires authentication

Location: config.rs:463-467, 620-629

Effective Auth Mode Logic

pub fn effective_auth_mode(&self) -> ProxyAuthMode {
    match self.auth_mode {
        ProxyAuthMode::Auto => {
            if self.allow_lan_access {
                ProxyAuthMode::AllExceptHealth
            } else {
                ProxyAuthMode::Off
            }
        }
        ref other => other.clone(),
    }
}

Location: security.rs:25-37

Request Security

User-Agent Override

user_agent_override · string

Custom User-Agent header for upstream requests

Use Cases:

• Bypass overly strict API filtering
• Add application identification
• Debug request routing

Example: antigravity/1.15.8 darwin/arm64

Location: config.rs:515

saved_user_agent · string

Persisted User-Agent value

Retained even when user_agent_override is disabled, for quick re-enabling.

Location: config.rs:536-537

Proxy Pool Security

Proxy Authentication

proxy_pool.proxies[].auth · object

Authentication credentials for upstream proxy

Location: config.rs:648-649

proxy_pool.proxies[].auth.username · string

Proxy username

Location: config.rs:635

proxy_pool.proxies[].auth.password · string

Proxy password (encrypted at rest)

Uses custom serialization for security:

#[serde(
    serialize_with = "crate::utils::crypto::serialize_password",
    deserialize_with = "crate::utils::crypto::deserialize_password"
)]

Location: config.rs:637-640

Proxy Configuration Example

{
  "proxy_pool": {
    "enabled": true,
    "proxies": [
      {
        "id": "proxy-1",
        "name": "US Residential",
        "url": "http://proxy.example.com:8080",
        "auth": {
          "username": "user123",
          "password": "encrypted_password_here"
        },
        "enabled": true,
        "priority": 1
      }
    ]
  }
}

Token & Credential Storage

All sensitive data is stored in platform-specific secure locations:

Storage Locations

• macOS: ~/Library/Application Support/com.antigravity.app/
• Linux: ~/.config/antigravity/
• Windows: %APPDATA%\antigravity\

Encryption

Proxy passwords are encrypted using the crypto utilities module before storage.

OAuth tokens are stored with restricted file permissions (0600).

Best Practices

Development

{
  "allow_lan_access": false,
  "auth_mode": "off",
  "security_monitor": {
    "blacklist": { "enabled": false },
    "whitelist": { "enabled": false }
  }
}

Production (Local Network)

{
  "allow_lan_access": true,
  "auth_mode": "all_except_health",
  "security_monitor": {
    "blacklist": { "enabled": true },
    "whitelist": { 
      "enabled": true,
      "whitelist_priority": true 
    }
  },
  "admin_password": "strong-unique-password"
}

Production (Internet-Exposed)

Not Recommended: Exposing the proxy to the internet is not recommended. Use a VPN or SSH tunnel instead.

If absolutely necessary:

{
  "allow_lan_access": true,
  "auth_mode": "strict",
  "security_monitor": {
    "blacklist": { "enabled": true },
    "whitelist": { 
      "enabled": true,
      "whitelist_priority": true 
    }
  },
  "admin_password": "very-strong-unique-password",
  "user_agent_override": "custom-app/1.0"
}

Security Checklist

✅ Use strong, unique API keys
✅ Set separate admin password for web UI
✅ Enable authentication when allowing LAN access
✅ Regularly rotate API keys
✅ Monitor access logs for suspicious activity
✅ Use IP whitelist for known clients
✅ Keep the application updated
✅ Restrict file permissions on config files
✅ Use upstream proxy with authentication if needed
✅ Enable debug logging only when troubleshooting

Troubleshooting

Authentication Failed

1. Verify api_key format (must start with sk-)
2. Check auth_mode configuration
3. Confirm client is sending Authorization: Bearer <key> header
4. Review proxy logs for authentication errors

IP Blocked

1. Check blacklist configuration
2. Verify whitelist if enabled
3. Review block_message for details
4. Check proxy access logs

Web UI Login Failed

1. Verify admin_password is set (or use api_key)
2. Clear browser cache/cookies
3. Check browser console for errors
4. Restart proxy service