Antigravity Manager - TypeScript CLI

Multi-account AI API proxy with smart token rotation and quota management. Headless CLI tool for managing Google and Anthropic accounts with intelligent request routing.

Quickstart (5 minutes)

1. Install

# Using npm
npm install -g antigravity-manager

# Or clone and build
git clone <repository-url>
cd typescript-antigravit-manager
npm install && npm run build
npm link  # Makes 'antigravity' command available globally

2. Add Your First Account

# Start OAuth flow for Google account
antigravity oauth google

# Follow the browser prompts to authorize
# Your tokens are securely stored with AES-256-GCM encryption

3. Start the Proxy Server

# Start on default port 3000
antigravity start

# Or specify a custom port
antigravity start --port 8080

4. Make Your First Request

# Use it as a drop-in replacement for OpenAI API
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

That's it! The proxy automatically routes your request through your authorized Google account, using Gemini models under the hood.

Features

• 🔐 Multi-account OAuth management - Support for Google and Anthropic accounts
• 🔄 Smart token rotation - Weighted round-robin with session affinity
• 📊 Real-time quota monitoring - Track usage across all accounts
• 🌐 Multi-protocol API proxy - OpenAI-compatible API, automatic model mapping
• 🔒 Encrypted token storage - AES-256-GCM encryption at rest
• ⚡ High-performance server - Fastify with streaming support
• 📝 SQLite database - WAL mode for concurrent access
• 📈 Prometheus metrics - Built-in /metrics endpoint for monitoring
• 🧪 Comprehensive testing - 80%+ test coverage

Technology Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js 20+ | | Language | TypeScript 5.3+ (ESM) | | HTTP Framework | Fastify 4.x | | Database | better-sqlite3 (SQLite with WAL) | | Testing | Vitest | | CLI | Commander.js + Inquirer.js | | Logging | Pino | | Build | tsup (esbuild) |

Installation

Prerequisites

• Node.js 20 or higher
• npm 10+

From npm (Recommended)

npm install -g antigravity-manager

From Source

# Clone the repository
git clone <repository-url>
cd typescript-antigravit-manager

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Environment Setup

Create a .env file in the project root:

# OAuth Credentials
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Encryption key (32+ characters recommended)
ENCRYPTION_KEY=your-secure-encryption-key-here

# Optional settings
PORT=3000
HOST=127.0.0.1
LOG_LEVEL=info

CLI Commands

Server Management

# Start the proxy server
antigravity start                    # Default port 3000
antigravity start --port 8080        # Custom port
antigravity start --host 0.0.0.0     # Bind to all interfaces
antigravity start --daemon           # Run in background

# Stop the server
antigravity stop

# Check server status
antigravity status

Account Management

# Add accounts via OAuth
antigravity oauth google             # Add Google account
antigravity oauth anthropic          # Add Anthropic account

# List all accounts
antigravity account list             # All accounts
antigravity account list --available # Only available accounts

# Remove an account
antigravity account remove <id>

Configuration

# View configuration
antigravity config show              # Show all config
antigravity config get <key>         # Get specific value

# Set configuration
antigravity config set server.port 8080
antigravity config set token.rotationStrategy weighted-round-robin

API Usage

The proxy exposes an OpenAI-compatible API at /v1/chat/completions.

Basic Request

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Streaming Request

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Count to 10"}],
    "stream": true
  }'

Model Mapping

| OpenAI Model | → Gemini Model | |-------------|----------------| | gpt-4 | gemini-2.0-flash-thinking-exp | | gpt-4-turbo | gemini-2.0-flash-exp | | gpt-4o | gemini-exp-1206 | | gpt-3.5-turbo | gemini-1.5-flash |

Using with LangChain

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  modelName: "gpt-4",
  configuration: {
    baseURL: "http://localhost:3000/v1",
  },
});

const response = await model.invoke("Hello, world!");

Using with OpenAI SDK

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'http://localhost:3000/v1',
  apiKey: 'not-needed',  // Proxy handles auth
});

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
});

Monitoring

Prometheus Metrics

The server exposes Prometheus-compatible metrics at /metrics:

curl http://localhost:3000/metrics

Available Metrics:

| Metric | Type | Description | |--------|------|-------------| | process_uptime_seconds | Gauge | Server uptime | | http_requests_total | Counter | Total requests by model and status | | http_request_duration_milliseconds | Summary | Request latency percentiles (p50, p95, p99) | | token_selection_duration_milliseconds | Summary | Token selection performance | | process_memory_bytes | Gauge | Memory usage (RSS, heap) |

Grafana Dashboard

Example Prometheus/Grafana configuration:

# prometheus.yml
scrape_configs:
  - job_name: 'antigravity'
    static_configs:
      - targets: ['localhost:3000']
    scrape_interval: 15s

Health Check

curl http://localhost:3000/health
# Returns: {"status":"ok","timestamp":"2024-01-01T00:00:00.000Z"}

Troubleshooting

Common Issues

Server won't start

# Check if port is in use
lsof -i :3000

# Try a different port
antigravity start --port 8080

OAuth flow fails

# Verify environment variables
echo $GOOGLE_CLIENT_ID
echo $GOOGLE_CLIENT_SECRET

# Check OAuth callback URL matches your Google Cloud Console configuration
# Default callback: http://localhost:8765/callback

No available accounts error

# Check account status
antigravity status

# Verify accounts exist and have quota
antigravity account list --available

# Re-authenticate if needed
antigravity oauth google

Database locked errors

# SQLite uses WAL mode, but issues can occur with multiple processes
# Stop all instances and restart
antigravity stop
antigravity start

Debug Mode

# Run with debug logging
LOG_LEVEL=debug antigravity start

# Or set in .env
echo "LOG_LEVEL=debug" >> .env

Production Deployment

systemd Service

Create /etc/systemd/system/antigravity.service:

[Unit]
Description=Antigravity Manager Proxy
After=network.target

[Service]
Type=simple
User=antigravity
WorkingDirectory=/opt/antigravity
ExecStart=/usr/bin/node /opt/antigravity/dist/cli/index.js start
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=LOG_LEVEL=info

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable antigravity
sudo systemctl start antigravity

# Check status
sudo systemctl status antigravity

Docker

FROM node:20-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
COPY data/ ./data/

EXPOSE 3000
CMD ["node", "dist/cli/index.js", "start", "--host", "0.0.0.0"]

# Build and run
docker build -t antigravity .
docker run -p 3000:3000 -v $(pwd)/data:/app/data antigravity

Nginx Reverse Proxy

upstream antigravity {
    server 127.0.0.1:3000;
}

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

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://antigravity;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}

Development

Setup

# Install dependencies
npm install

# Run in development mode with watch
npm run dev

# Run server standalone
npm run dev:server

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific suite
npm test -- tests/unit
npm test -- tests/integration

Building

# Production build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

Project Structure

typescript-antigravit-manager/
├── src/
│   ├── cli/                 # CLI entry point and commands
│   ├── server/              # Fastify HTTP server
│   │   ├── routes/          # API route handlers
│   │   └── index.ts         # Server configuration
│   ├── modules/             # Core business logic
│   │   ├── account/         # Account management
│   │   ├── token/           # Token selection & rotation
│   │   ├── oauth/           # OAuth providers
│   │   ├── quota/           # Quota monitoring
│   │   ├── config/          # Configuration management
│   │   └── monitoring/      # Metrics collection
│   ├── protocols/           # API protocol handlers
│   │   ├── openai/          # OpenAI format handling
│   │   └── gemini/          # Gemini API client
│   ├── database/            # SQLite database layer
│   └── utils/               # Shared utilities
├── tests/
│   ├── unit/                # Unit tests
│   └── integration/         # Integration tests
├── docs/                    # Documentation
└── dist/                    # Compiled output

Performance

| Metric | Target | Actual | |--------|--------|--------| | Server startup | < 100ms | ~80ms | | Request routing | < 5ms overhead | ~2ms | | Token selection | < 1ms | ~0.5ms | | Memory (idle) | < 100MB | ~50MB | | Bundle size | < 500KB | ~450KB |

Security

• Encryption at Rest: All OAuth tokens encrypted with AES-256-GCM
• Secure Key Derivation: PBKDF2 with random salt per token
• No Credential Logging: Tokens never appear in logs
• CORS Configuration: Configurable origin restrictions
• Rate Limiting: Per-client rate limiting support

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run npm test to ensure all tests pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see LICENSE for details.

Documentation

• Project Specification
• Architecture
• API Documentation
• Troubleshooting Guide
• Migration Guide
• Changelog