Flagship features · AI gateway HTTP API

AI gateway

An external program sends {ai, prompt} over a local HTTP API, and orchterm spins up that AI (claude·codex·agy) in a worker tab, runs one turn, and returns the response synchronously — an automated call with no human in the loop.

What it does

When an external program (a script · CI · an in-app browser page) sends a one-line prompt, the gateway spins up a worker AI in a tab, runs one turn, and returns an OpenAI-compatible response while holding the connection open.

caller

External programHTTP client

POST /run

{ai, prompt}

orchterm

HTTP server:9610 · Bearer

worker tab

run 1 turn

worker

claude · codex · agyworker tab (1 turn)

Getting started

Turn on the gateway (applied after restart)

A fresh install starts with the gateway on. Turning it off or back on takes effect after an app restart.
Check · copy the Bearer token

The token is issued randomly once, the first time. Check and copy it under Settings → AI gateway and hand it to the caller. Every request needs Authorization: Bearer …, and a mismatch returns 401.

① It binds to 127.0.0.1 only, so there's no external network exposure · copy the token and hand it to the caller.

Workers run from a fixed folder (~/.orchterm/gateway), so agent trust approval is needed only once, the first time.

API call — POST /run

The request is POST /run (alias POST /v1/chat/completions). Put the AI to call and the prompt in the body, and it holds the connection until the response arrives, returning OpenAI chat.completion JSON synchronously.

curl — synchronous call200 · chat.completion

POST /run · request

$ curl -s http://127.0.0.1:9610/run \
    -H "Authorization: Bearer $ORCHTERM_GATEWAY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "agent": "claude", "prompt": "PING", "session": "s1" }'

200 OpenAI chat.completion · response

{
  "id": "req_8f3a…", "object": "chat.completion",
  "choices": [
    { "index": 0,
      "message": { "role": "assistant", "content": "PONG" },
      "finish_reason": "stop" }
  ],
  "result": "PONG", "error": null // result·error = legacy compat
}

① Synchronous model — the server waits up to 360s, then returns 504 if it hasn't finished.

Body field	Meaning
`agent` / `ai`	Worker type — claude · codex · agy (default `claude`)
`prompt` / `messages`	The prompt to send. If both are empty, `400`
`session`	keepalive key (optional) — a value reuses the worker, empty makes it one-shot
`model`	Passed to the claude worker as `--model` (ignored for codex and agy). It applies when the worker starts, so reusing a worker via `session` keeps the model from the first call

Session keepalive (multi-turn)

Give a session value and the same session reuses the same worker — multi-turn with context preserved. Leave it empty and it's one-shot, closing the worker after the response (“the worker disappeared after the response” is not a bug but this very behavior).

session "s1" — context preserved

# turn 1 — first call with the same session $ curl …/run -d '{ "agent":"claude", "session":"s1", "prompt":"remember: banana73" }' ◂ "Got it. I've remembered 'banana73'." # turn 2 — same session, worker reused → recall $ curl …/run -d '{ "agent":"claude", "session":"s1", "prompt":"what was that code earlier?" }' ◂ "It's banana73."

▲ turn 2 recalls turn 1's “banana73” — reusing the same worker and the same session.

Worker safe mode (ON by default)

Gateway workers run in safe mode by default — they don't use the dangerous permission-bypass flag. Bypass mode (unattended · faster but not recommended) is only enabled via the setting “Bypass dangerous worker permissions”.

Caution — the gateway is the control plane through which external programs put local AI to work. Don't carelessly disable the token, the local binding, or the safe-mode default.

Audit log (request/response records + viewer tab)

While the gateway is on, it logs every request that passes authentication, by date — prompt · timestamp · total time · status (ok·error·timeout) · down to the raw response. Open the viewer tab with the palette command “Gateway audit log”.

Gateway audit log — viewer tab

Gateway audit log

2026-06-28

Requests (recent 24 / 24 total)

14:02:51remember: bana…na733.1sok

14:02:09PING2.4sok

13:58:44SSH tunnel…ty review41.8sok

13:55:02large rep…rse summary360stimeout

═══ drag ═══

Raw request

{ "agent": "claude", "session": "s1",
  "prompt": "remember: banana73" }

Raw response

{ "result": "Got it. I've remembered 'banana73'.",
  "error": null } // totalMs 3142 · status ok

‹ 2026 · June ›

SunMonTueWedThuFriSat 31123456 78910111213 14151617181920 21222324252627 2829301234

① Date → calendar popup (only days with logs are selectable). ② Request list on top ↕ details below (raw request·response).

Retention days are set in settings (default 10 days) — dates beyond that are deleted automatically. The full raw response is stored.