Skip to main content

Install

From an empty machine to a working completion. Docker is the easy path; Go works if you’d rather skip containers.

1. Clone​

git clone https://github.com/teslashibe/open-agent-api.git
cd open-agent-api

2. Log in upstream​

You need at least one surface. Codex is the usual starting point:

# Codex / ChatGPT (needed for gpt-* models)
codex login

# Optional — Gemini 3.x / Antigravity
scripts/sync-antigravity-auth.sh

# Optional — Claude Code CLI
# install Claude Code, then finish `claude` login

More detail: Auth overview.

3. Start the API​

Needs Docker + Docker Compose.

docker compose up --build -d

It listens on http://127.0.0.1:8088. Extra Compose notes: Install with Docker.

Go (no Docker)​

Needs Go 1.24+.

go run ./cmd/open-agent-api --host 127.0.0.1 --port 8088

4. Health check​

curl -s http://127.0.0.1:8088/health
# → {"status":"ok"}

curl -s http://127.0.0.1:8088/v1/models | jq '.data[].id'

5. First completion​

curl -s http://127.0.0.1:8088/v1/chat/completions \
  -H 'authorization: Bearer local-open-agent-api' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Say hi in five words."}
    ]
  }' | jq .

You should get OpenAI-shaped JSON with choices[0].message.content. Streaming looks like this:

curl -N http://127.0.0.1:8088/v1/chat/completions \
  -H 'authorization: Bearer local-open-agent-api' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.6-terra",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count to five."}
    ]
  }'

When GATEWAY_BEARER_SECRET is unset (the local default), the bearer can be any non-empty string.

Localhost is fine for curl and SDKs on the same machine. Cursor BYOK can’t use localhost — keep going to step 6.

6. Cursor (needs a public HTTPS tunnel)​

Cursor sends BYOK through its cloud and rejects private networks (Access to private networks is forbidden). Tunnel the API with your own ngrok domain:

# Authtoken: https://dashboard.ngrok.com/get-started/your-authtoken
NGROK_AUTHTOKEN=... docker compose -f docker-compose.yml -f docker-compose.ngrok.yml up -d

curl -s https://YOUR_SUBDOMAIN.ngrok-free.dev/health
# → {"status":"ok"}

In Cursor → Settings → Models:

FieldValue
OpenAI API Keylocal-open-agent-api (any non-empty string)
Override OpenAI Base URLhttps://YOUR_SUBDOMAIN.ngrok-free.dev/v1
Modele.g. gpt-5.6-terra

Open a new Agent chat and try: List the files in this repo.

Full walkthrough: Cursor BYOK + ngrok.

Next​