omnigateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harismawan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# OmniGateway
+
+One endpoint in front of the AI accounts you already pay for.
+
+OmniGateway is a self-hosted gateway that speaks the Anthropic and OpenAI APIs
+and answers them using your own Anthropic, OpenAI, and Kimi Coding
+subscriptions. Point any compatible client at it, ask for a model you defined,
+and the gateway picks an account that can serve it — falling back to another
+when one is rate-limited, expired, or out of quota.
+
+It runs on one machine, stores everything in a local SQLite file, and never
+logs the contents of your prompts or replies.
+
+```bash
+bun install -g omnigateway
+omni start
+```
+
+> Status: in use and complete for its scope. Version 1 targets a single
+> machine and a single operator — see [Scope](#scope-and-limits).
+
+## What it does
+
+- **Speaks both dialects.** `POST /v1/messages` (Anthropic) and
+  `POST /v1/chat/completions` (OpenAI), including streaming, translated to
+  whichever provider actually serves the request.
+- **Routes across your accounts.** Define a virtual model like `fast` or
+  `smart` with several targets; the gateway ranks them by tier, health,
+  remaining quota, cost, and latency.
+- **Fails over.** A rate-limited or broken account is skipped, its circuit
+  breaker opens, and the next candidate is tried — before the response starts
+  streaming.
+- **Keeps OAuth alive.** Tokens refresh in the background, before a request
+  needs them.
+- **Watches provider quota.** It asks each provider what you have left and
+  routes by *pace*: 5% remaining is fine minutes before a reset and urgent with
+  six days to run.
+- **Issues its own keys.** Hand out gateway keys with per-key model allowlists
+  and rate limits instead of sharing provider credentials.
+- **Reports usage.** Requests, tokens, and cost by provider, model, key, and
+  day — metadata only.
+- **Ships an admin console and a CLI.** Both cover the same ground; use
+  whichever suits the machine you are on.
+
+## Requirements
+
+- [Bun](https://bun.sh/) 1.4 or later. Bun is the runtime, not just the
+  installer, so a Node-only machine cannot run OmniGateway.
+- A directory that persists, for the SQLite database.
+- At least one Anthropic, OpenAI, or Kimi Coding account to connect.
+
+## Install
+
+```bash
+bun install -g omnigateway     # or: npm i -g omnigateway
+```
+
+One package carries the `omni` CLI, the gateway server, and the admin console
+the server hosts.
+
+## Getting started
+
+Pick a directory to hold the database and configuration. `~/.config/omnigateway`
+is where `omni` looks by default:
+
+```bash
+mkdir -p ~/.config/omnigateway && cd ~/.config/omnigateway
+printf 'OMNI_ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" > .env
+```
+
+That key encrypts your provider credentials at rest. **Keep it. Changing it
+makes every stored credential unreadable**, and there is no recovery path
+except reconnecting the accounts.
+
+Then set up and start:
+
+```bash
+omni db migrate            # create the database
+omni admin set-password    # prompts; the console signs in with this
+omni start                 # serves the API and the console on 127.0.0.1:8787
+```
+
+Connect an account. The CLI prints a URL to open, and waits:
+
+```bash
+omni connect anthropic     # or: openai, kimi
+```
+
+Define a virtual model your clients will ask for, seeding its pricing and
+capabilities from the built-in catalog:
+
+```bash
+omni models catalog                                  # what is available
+omni models put fast --from-catalog anthropic:claude-sonnet-5
+```
+
+Mint a key for your client. **It is printed once and stored only as a hash:**
+
+```bash
+omni keys create --label laptop
+```
+
+Now use it:
+
+```bash
+curl http://127.0.0.1:8787/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <gateway-key>' \
+  -d '{"model": "fast", "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+Everything above is also available in the browser at
+`http://127.0.0.1:8787`, which walks the same steps.
+
+## Using it from a client
+
+| Method | Path | Compatible with |
+| --- | --- | --- |
+| `POST` | `/v1/messages` | Anthropic Messages API |
+| `POST` | `/v1/chat/completions` | OpenAI Chat Completions API |
+| `GET` | `/v1/models` | OpenAI-style listing, filtered by your key's allowlist |
+| `GET` | `/health` | Unauthenticated liveness check |
+
+Authenticate with either header — sending both is an error:
+
+```http
+Authorization: Bearer <gateway-key>
+x-api-key: <gateway-key>
+```
+
+Ask for one of your virtual models by name. A bare provider model
+(`claude-sonnet-5`, `gpt-5`) also works if an account can serve it.
+
+Most tools that accept a custom base URL work unchanged: set it to
+`http://127.0.0.1:8787` and use a gateway key where the provider key goes.
+
+## The CLI
+
+`omni --help` lists everything; `omni <command> --help` explains one. Every
+command takes `--json` for scripting, and `--root <path>` to manage an
+installation other than the default.
+
+| | |
+| --- | --- |
+| `omni status` | the gateway, its accounts, and their quota, on one screen |
+| `omni start` / `stop` / `restart` | run the gateway; `--foreground` attaches it to your terminal |
+| `omni doctor` | which installation it resolved, and whether it can act on it |
+| `omni logs` | recent requests as the gateway recorded them |
+| `omni usage` | spend and tokens, by provider, model, key, or day |
+| `omni connect <provider>` | authorize an account from the terminal |
+| `omni credentials …` | list, show, enable, disable, retier, refresh, remove |
+| `omni models …` | list, show, put, remove, `dry-run`, `catalog` |
+| `omni keys …` | list, create, revoke |
+| `omni settings get` / `set` | routing weights, retention, deadlines |
+| `omni admin set-password` | change the console password |
+| `omni db migrate` | create or upgrade the database |
+
+Two worth knowing:
+
+`omni models dry-run fast` shows exactly where a request would go and why —
+each candidate's score, and every account that was excluded with the reason.
+
+`omni status` is the "is anything wrong" command: process state, per-account
+health, and how much provider quota each account has left.
+
+## Running it as a service
+
+On a machine with systemd:
+
+```bash
+omni service install --enable    # writes a user unit for this installation
+omni start                       # from here on, start/stop delegate to systemctl
+omni logs --service              # reads the journal
+```
+
+Use `--system` for a system-wide unit (needs root). Without systemd, `omni
+start` supervises the process itself with a pidfile under
+`~/.local/state/omnigateway`. Either way, `omni start` returns only once
+`/health` actually answers.
+
+## Configuration
+
+Configuration is environment variables, read from the installation's `.env`:
+
+| Variable | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `OMNI_ENCRYPTION_KEY` | Yes | — | Encrypts provider credentials at rest; 16 characters minimum |
+| `OMNI_HOST` | No | `127.0.0.1` | Listener host |
+| `OMNI_PORT` | No | `8787` | Listener port |
+| `OMNI_DB_PATH` | No | `./omnigateway.db` | SQLite database path |
+| `OMNI_BASE_URL` | No | derived from host and port | Public origin for OAuth callbacks; set this behind a reverse proxy |
+| `OMNI_STATIC_DIR` | No | the console shipped with the server | Serve a different console build |
+
+Routing behaviour — weights, retry limits, request deadline, log retention,
+how often provider quota is polled — lives in the database, not the
+environment. Edit it with `omni settings set` or in the console.
+
+`.env.example` in the repository documents the optional provider
+client-identity overrides.
+
+## Docker
+
+```bash
+docker build -t omnigateway .
+docker run --rm \
+  -p 8787:8787 \
+  -e OMNI_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
+  -v omnigateway-data:/data \
+  omnigateway
+```
+
+The container listens on `0.0.0.0:8787` and keeps its database at
+`/data/omnigateway.db`. Note that **the image builds the gateway only**: it
+serves the APIs and returns 404 for the console. Use the CLI or the control API
+against it, or install the npm package if you want the console.
+
+## Scope and limits
+
+Worth knowing before you deploy it:
+
+- **One machine, one operator.** No multi-tenancy, no clustering, no shared
+  state. Rate limits are counted per process and reset when it restarts.
+- **Two grains of usage history.** Detailed request logs are pruned after 30
+  days by default; a daily rollup is kept for 400 days. A day is your host's
+  local midnight, fixed when the row is written.
+- **Quota readings come from the providers**, and their usage endpoints are
+  undocumented. An account with nothing reported is treated as unknown, never
+  as unlimited.
+- **The gateway does not know which model accepts which request shape.** An
+  unsupported combination surfaces as the provider's own 400 rather than being
+  caught earlier.
+- Not in scope for version 1: semantic caching, billing, prompt storage,
+  horizontal scaling.
+
+## Security
+
+- Treat `OMNI_ENCRYPTION_KEY`, gateway keys, and the SQLite file as secrets.
+  Anyone with the file *and* the key has your provider credentials.
+- Prompts and responses are never logged. Request logs hold metadata and token
+  counts only.
+- Gateway keys are stored as hashes. A lost key is reissued, not recovered.
+- Secrets are never accepted on the command line — `omni` prompts for them or
+  reads stdin — so they stay out of your shell history and the process table.
+- Behind a reverse proxy, set `OMNI_BASE_URL` to the public HTTPS origin so
+  OAuth callbacks match what the providers have registered.
+- The gateway talks to your providers and to nobody else. No telemetry, no CDN
+  fonts, no third-party origins.
+
+## Development
+
+Contributing, or running from a checkout? See [CLAUDE.md](CLAUDE.md) for the
+repository map, architectural boundaries, and conventions, and
+`docs/superpowers/specs/` for the design documents behind each feature.
+
+```bash
+git clone https://github.com/harismawan/omnigateway.git
+cd omnigateway
+bun install
+cp .env.example .env          # then set OMNI_ENCRYPTION_KEY
+bun run build:dashboard       # the gateway serves this build
+bun run dev                   # gateway on 8787, with file watching
+```
+
+Releases are published to npm from a `v*` tag, with provenance attesting which
+commit produced them.