Orbiton Documentation

Orbiton is your AI & API Mission Control — a unified dashboard and proxy gateway for managing AI providers, virtual keys, agents, and usage analytics.

1. Create an Account

Sign up at the registration page with your email and password, or use OAuth (GitHub/Google). An organization is automatically created for you.

2. Add Provider Credentials

Go to Settings and add your API keys for OpenAI, Anthropic, or Google. Keys are encrypted at rest using AES-256-GCM and never exposed to the frontend.

3. Create a Project

Projects group your resources by product or service. Create one under Projects with a name, description, and color.

4. Generate a Virtual Key

Under Virtual Keys, create a key linked to a project and credential. You'll get a key starting with orb_ — use this as a drop-in replacement for your provider's API key.

5. Make API Calls

Route your AI requests through Orbiton's proxy. Replace your provider's base URL with Orbiton's proxy endpoint:

curl -X POST https://your-orbiton.vercel.app/api/v1/proxy/openai/v1/chat/completions \
  -H "Authorization: Bearer orb_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}]}'

Proxy Endpoint

POST /api/v1/proxy/:provider/*endpoint

Forwards requests to the specified provider. Supported providers: openai, anthropic, google, mistral, deepseek, xai.

Headers:

• Authorization: Bearer orb_... — Your virtual key
• Content-Type: application/json

Agent Registration

POST /api/v1/agents

Register a new agent. Requires a JSON body with projectId, name, and optionally virtualKeyId and heartbeatIntervalS.

Agent Heartbeat

POST /api/v1/agents/:id/heartbeat

Send a heartbeat signal. Include Authorization: Bearer orb_.... Optional JSON body with status and metadata.

curl -X POST https://your-orbiton.vercel.app/api/v1/agents/AGENT_ID/heartbeat \
  -H "Authorization: Bearer orb_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "healthy", "metadata": {"cpu": 45, "memory": 72}}'

Health Check Cron

GET /api/cron/health-checks

Runs all due health checks. Protected by CRON_SECRET via Bearer token. Configure in Vercel cron or external scheduler.

Virtual Keys are the core of Orbiton's gateway. They provide a security and control layer between your applications and AI providers.

Features

• Kill Switch — Instantly deactivate a key without changing application code
• Budget Limits — Set monthly spending caps per key (tracked with real pricing data)
• Rate Limiting — Configure requests-per-minute limits
• Model Restrictions — Allowlist specific models per key
• Expiration — Set automatic key expiry dates
• Key Rotation — Rotate keys without downtime

How It Works

When a request hits the proxy, Orbiton: resolves the virtual key hash, checks kill switch / expiry / budget / rate limit / allowed models, decrypts the linked provider credential, forwards the request, logs usage with cost estimation, and returns the response.

Track your AI agents in real-time. Agents register with Orbiton and send periodic heartbeats to report their status.

Status Computation

• Healthy — Heartbeat received within the expected interval
• Degraded — Heartbeat delayed (1-2x interval)
• Offline — No heartbeat for 2x+ the interval
• Unknown — No heartbeat ever received

Heartbeat Protocol

Agents should send heartbeats at their configured interval (default: 60 seconds). Each heartbeat can include optional metadata (CPU, memory, custom metrics). Rate limited to 12 heartbeats/minute per agent.

Monitor your project infrastructure with configurable health checks. Three check types are available:

URL Checks (HTTPS)

Send HEAD requests to HTTPS endpoints. SSRF protection blocks private/local addresses. 10-second timeout. Status determined by HTTP response code.

Database Checks (TCP)

TCP connectivity checks to database host:port. No credentials needed — just verifies the service is reachable. Private IP addresses are blocked.

Agent-Based Checks

Aggregates the health status of all agents in a project. If all agents are healthy, the check is healthy. If any are offline, it reports as down.

Checks run on a configurable interval (minimum 60 seconds, default 300 seconds) via the cron endpoint.

Orbiton analyzes your API usage patterns and provides actionable cost optimization recommendations.

Model Recommender

The optimizer analyzes your last 30 days of usage per model and computes hypothetical costs with every alternative in our pricing database. It recommends same-tier alternatives (equal capability, lower cost) and budget alternatives (cheaper tier for cost-sensitive workloads).

Wasted Spend Report

Failed API requests (4xx/5xx) still consume input tokens. The wasted spend report groups errors by model, provider, and status code, calculates the total cost impact, and provides actionable recommendations (e.g., "Rate limited — spread load across multiple keys").

Per-Key Spend Drilldown

See exactly which virtual keys and models are driving your costs. Each key shows its spend, budget status, and a suggested budget based on the formula: ceil(dailyAvg * 31 * 1.15) — 15% headroom over a 31-day projection.

Error Heatmap

A 24-hour error density heatmap shows when your API errors cluster, helping you identify patterns like rate limit spikes during peak hours.

Orbiton offers three plan tiers for cloud deployments. Self-hosted installations automatically get Enterprise features.