Run Hyperagent.com behind an OpenAI-compatible API. Point any OpenAI client
(the openai SDK, Cursor, Continue, LibreChat, LangChain, β¦) at this gateway and
call the endpoints you already know β /v1/chat/completions, /v1/models,
/v1/responses, and more. The gateway translates each request into Hyperagent
operations and returns responses in exact OpenAI wire format (streaming
included).
In one sentence: your existing OpenAI code keeps working, but the "model" answering is a full Hyperagent agent that can search the web, run code, use a browser, generate media, and call your integrations.
π Full documentation: English docs Β· TΓ i liα»u tiαΊΏng Viα»t
- What is this?
- How it works
- Quick start
- Connect your client
- Supported endpoints
- The tool bridge
- Multi-user / multi-tenant
- Configuration
- Deployment
- Testing
- Project structure
- Limitations
- FAQ
- License
The OpenAI API is a de-facto standard: a huge amount of software knows how to "talk" to it. Hyperagent.com is a platform where AI agents do real work inside persistent threads (research, code, browser automation, media, files, integrations). Its only public programmatic door is a hosted MCP server (Model Context Protocol) β not an OpenAI-style API.
This project is the adapter between those two worlds. Think of it as a universal power plug: your device (the OpenAI client) plugs in the same way as always, and behind the wall the electricity actually comes from Hyperagent.
Who is it for?
- People who already have OpenAI-based apps and want an agent backend without rewriting their code.
- Tools that only speak "OpenAI" (IDEs, chat UIs) but want Hyperagent's power.
New to these terms? Start with Overview & concepts.
OpenAI-compatible client (Cursor, Continue, LibreChat, openai SDK, β¦)
β HTTP: POST /v1/chat/completions (Authorization: Bearer <gateway key>)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββ
β Gateway (FastAPI) β
β β’ Auth: gateway key β a Hyperagent identity β
β β’ Translate: OpenAI β Hyperagent thread ops β
β β’ UpstreamAdapter: MCP (real) | Mock (dev) β
βββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP JSON-RPC 2.0 over HTTPS (OAuth 2.1 Bearer token)
βΌ
Hyperagent MCP server https://hyperagent.com/api/mcp
β list_agents Β· create_thread Β· get_thread (poll) Β· send_message Β· β¦
βΌ
Your Hyperagent agent runs the request end-to-end
(web search, browser, shell, files, images/audio, integrations)
Key ideas:
model= a Hyperagent agent.GET /v1/modelslists your agents; pick one as themodel, or use the aliashyperagent-default.- A request = a thread run. Hyperagent runs in the background, so the gateway polls until the answer is ready.
- Streaming is emulated. Hyperagent doesn't stream tokens, so the gateway turns poll updates into standard OpenAI SSE chunks.
- Stateless by design. Every call is self-contained (see Architecture); the gateway never relies on fragile upstream memory.
Prerequisites: Python 3.11+ (except the Docker path). On Windows, install
Python from python.org and tick "Add
python.exe to PATH" β that also gives you the py launcher.
1. Install β the universal way (works on Windows, macOS, Linux):
pip install git+https://github.com/dinhhung893/hyperagent-openai-gatewayWindows PowerShell: if
pipisn't found, usepy -m pip install git+β¦.
This gives the hyperagent-gateway command (alias hga). If your shell can't find
it, the exact equivalent always works: python -m gateway.cli β¦
(Windows: py -m gateway.cli β¦).
Other install methods β pipx Β· uv Β· Docker Β· one-liner
| Method | macOS / Linux | Windows (PowerShell) |
|---|---|---|
| pipx | pipx install git+β¦ |
py -m pip install --user pipx; py -m pipx ensurepath β reopen shell β pipx install git+β¦ |
| uv | uvx --from git+β¦ hyperagent-gateway serve |
irm https://astral.sh/uv/install.ps1 | iex β uvx --from git+β¦ hyperagent-gateway serve |
| Docker | docker compose up -d --build |
docker compose up -d --build |
| one-liner | curl -fsSL https://raw.githubusercontent.com/dinhhung893/hyperagent-openai-gateway/main/install.sh | bash |
irm https://raw.githubusercontent.com/dinhhung893/hyperagent-openai-gateway/main/install.ps1 | iex |
Windows note: in PowerShell,
curlis an alias forInvoke-WebRequestand there is nobash, so thecurl β¦ \| bashline is for macOS/Linux/WSL only. Useinstall.ps1(viairm β¦ \| iex) instead.
2. Go live β two commands:
hga login # one-time Hyperagent sign-in (opens a browser)
hga serve # serves http://localhost:8000/v1Windows without the command on PATH:
py -m gateway.cli loginthenpy -m gateway.cli serve.
Just trying it? No account needed β run against the built-in mock:
hga serve --upstream mock # or: py -m gateway.cli serve --upstream mockYour Hyperagent account needs at least one named agent (the MCP server only starts threads on named agents). Check with
hga agents.
Full walkthrough: Quick start.
hyperagent-gateway (alias hga):
| Command | What it does |
|---|---|
hga init |
Write ~/.hyperagent-gateway/.env (interactive; --yes for defaults) |
hga login |
One-time OAuth (--remote-start / --remote-finish for headless servers) |
hga serve |
Run the gateway (--port, --upstream mcp|mock, --reload, β¦) |
hga agents |
List your Hyperagent agents |
hga doctor |
Check config + upstream reachability |
hga quickstart |
login (if needed) then serve |
Config is auto-loaded with precedence: CLI flags β environment β .env (current
dir, then ~/.hyperagent-gateway/.env) β defaults. So you can drop a .env and
skip long inline env vars. (uvicorn gateway.app:app still works for power users.)
There are two separate credentials β don't confuse them:
1. Your gateway API key (SHIM_API_KEYS) β the api_key your OpenAI client
sends. You choose it yourself; it is not fetched from anywhere. hga init and
the installers auto-generate one for you.
- View it:
cat ~/.hyperagent-gateway/.env(Windows PowerShell:Get-Content $env:USERPROFILE\.hyperagent-gateway\.env) β look for theSHIM_API_KEYS=line. - Set / generate it:
hga init(wizard), or edit.env(SHIM_API_KEYS=sk-yourkey; comma-separate several), or pass--api-keystoserve. - Dev mode: if
SHIM_API_KEYSis unset, the gateway accepts any key β but your client still needs a non-empty value, so just putsk-local(most OpenAI tools require a non-emptyapi_key, and some want thesk-prefix).
2. Your Hyperagent access β Hyperagent has no API key. The gateway signs in
once with OAuth (hga login) and stores a refreshable token; you never paste a
Hyperagent key anywhere.
So: hga login handles Hyperagent; SHIM_API_KEYS is a secret you set to protect
the gateway, and it's what clients use as their api_key.
OpenAI Python SDK
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="sk-mylocalkey")
print(client.models.list()) # your Hyperagent agents
r = client.chat.completions.create(
model="hyperagent-default",
messages=[{"role": "user", "content": "Research the latest on X and summarize"}],
)
print(r.choices[0].message.content)curl (macOS / Linux)
curl http://localhost:8000/v1/chat/completions \
-H "authorization: Bearer sk-mylocalkey" -H "content-type: application/json" \
-d '{"model":"hyperagent-default","messages":[{"role":"user","content":"Hello"}]}'PowerShell (Windows) β curl there is Invoke-WebRequest, so use:
Invoke-RestMethod -Uri http://localhost:8000/v1/chat/completions -Method Post `
-Headers @{ Authorization = "Bearer sk-mylocalkey" } -ContentType 'application/json' `
-Body '{"model":"hyperagent-default","messages":[{"role":"user","content":"Hello"}]}'Non-ASCII bodies (Vietnamese, etc.) work too β the gateway auto-repairs Windows Latin-1/CP1252 encoding. For strict correctness, use PowerShell 7.
Cursor / Continue / LibreChat / OpenWebUI: set the OpenAI Base URL to
http://localhost:8000/v1, the API key to one of your SHIM_API_KEYS, and
the model to an agent id from GET /v1/models.
| Endpoint | Status |
|---|---|
GET /v1/models, /v1/models/{id} |
β lists your Hyperagent agents |
POST /v1/chat/completions (stream + non-stream) |
β |
POST /v1/responses (+ background, cancel, input_items, stateful chains) |
β |
GET /v1/tools + forced tool_choice |
β tool bridge |
POST /v1/completions (legacy) |
β |
POST /v1/images/generations, /v1/images/edits |
β real fetchable URLs |
POST /v1/audio/speech, /transcriptions, /translations |
β |
POST /v1/files, GET/DELETE /v1/files/{id}, /content |
β + chat attachments |
POST /v1/embeddings |
β
local fallback (or 501 if disabled) |
POST /v1/moderations |
β heuristic |
Full parameter-by-parameter behavior: API reference.
Hyperagent agents have a rich toolbox (bash/shell, file read/write, web search,
browser, image/video/audio, tables, docs, maps, integrations). The gateway
exposes all of it through OpenAI's standard tools / tool_calls in three modes:
- Observe β an agent's tool activity shows up as
tool_callsin the reply. - Direct β force a capability with
tool_choice. - Run β a tool-runner executes a tool directly (e.g. run a shell command) and returns the result.
GET /v1/tools returns the full catalog. Details + examples:
Tool bridge.
One gateway can serve many Hyperagent users. Map each API key to its own
Hyperagent identity and policy via GATEWAY_KEYS_FILE:
[{"api_key":"sk-alice","token_file":"~/.hyperagent-gateway/alice.json","disabled_tools":["shell"]},
{"api_key":"sk-bob","token_file":"~/.hyperagent-gateway/bob.json"}]Each user authorizes once with tools/oauth_login.py. See
Deployment & security.
| Variable | Default | Meaning |
|---|---|---|
GATEWAY_UPSTREAM |
mcp |
mcp (real) or mock (offline) |
HYPERAGENT_MCP_URL |
https://hyperagent.com/api/mcp |
upstream endpoint |
HYPERAGENT_TOKEN_FILE |
~/.hyperagent-gateway/tokens.json |
OAuth token bundle |
SHIM_API_KEYS |
(empty = dev; clients still send any non-empty key, e.g. sk-local) |
comma-separated client keys |
GATEWAY_KEYS_FILE |
(none) | multi-tenant identity map (JSON) |
GATEWAY_DEFAULT_AGENT |
(first agent) | agent for hyperagent-default |
GATEWAY_EXEC_MODE |
roundtrip |
tool-runner mode: roundtrip or auto |
GATEWAY_DISABLED_TOOLS |
(none) | hide tools, e.g. shell,write_file |
GATEWAY_EMBEDDINGS |
fallback |
fallback or off |
GATEWAY_POLL_INTERVAL / GATEWAY_RUN_TIMEOUT |
1.0 / 600 |
polling |
Docker Compose (recommended for servers) β put settings in .env and your token
bundle in ./secrets/tokens.json:
docker compose up -d --buildFull guide (VPS, reverse proxy, HTTPS, multi-tenant, headless OAuth): Deployment.
python3.11 -m pytest tests/ -q # 46 tests: unit + ASGI API + OpenAI SDKgateway/ FastAPI app + translation + upstream adapters
app.py all HTTP routes
upstream/ mcp.py (real) Β· mock.py (dev) Β· base.py Β· manager.py
translate.py streaming.py toolbridge.py fallbacks.py media.py auth.py β¦
tools/ oauth_login.py, oauth_remote.py (one-time OAuth helpers)
tests/ 46 tests (mock upstream + OpenAI SDK)
docs/en/ docs/vi/ bilingual documentation
Dockerfile requirements.txt pyproject.toml
- Latency: each call runs a full agent pipeline β expect seconds, not milliseconds.
- Streaming is emulated (poll-based), not true token streaming.
- Sampling knobs (
temperature,top_p,seed) are best-effort / no-ops. - Embeddings use a local non-semantic fallback unless you wire a real provider.
- Auth is per-user OAuth (Hyperagent has no API keys); the gateway stores and refreshes each user's token.
A few quick ones (full list: FAQ):
- Do I need to change my OpenAI code? No β just the
base_urlandapi_key. - Which model do I pass? A Hyperagent agent id (
GET /v1/models) orhyperagent-default. - Is it really OpenAI-compatible? Yes; the official
openaiSDK works unmodified (tested).
No license file is included yet. Until one is added, all rights are reserved by the repository owner. Open an issue if you'd like a specific license (e.g. MIT).
Built on the Hyperagent MCP server. "OpenAI" is a trademark of OpenAI; this project is an independent compatibility layer and is not affiliated with OpenAI.