`openai-server://`¶

The inverse of openai:// — instead of calling OpenAI's API, this scheme runs an OpenAI-compatible HTTP server that fronts a Helix agent (or any consumer route). It accepts the standard POST /v1/chat/completions shape — streaming and non-streaming — and also implements GET /v1/models. Useful when you want existing OpenAI SDKs / clients (Cursor, Continue.dev, Open WebUI, the OpenAI Python SDK, any custom integration) to talk to a Helix-hosted agent without code changes.

openai-server is consumer-only. Wire it as the from: of a route; the route's steps become the assistant's behaviour.

URI shape¶

openai-server://<host>:<port>?agent=<id>&api_key=<token>

The path is the listen address (e.g. 0.0.0.0:8080). Anything after a / in the path (e.g. 0.0.0.0:8080/v1) is stripped — the server always exposes /v1/chat/completions, /v1/completions, /v1/models and /health regardless.

Parameters¶

Param	Type	Default	Producer/Consumer/Both	Description
path	string	`0.0.0.0:8080`	Consumer	`host:port` to listen on.
`agent`	string	(empty)	Consumer	The agent id this server fronts. Surfaced as the model name in `GET /v1/models` so OpenAI SDK clients can address the agent by name.
`api_key`	string	(empty — open)	Consumer	Bearer token required in the `Authorization` header. If unset, the server is open.

Producer mode is rejected — openai-server has no to: semantics.

Endpoints exposed¶

Path	Method	Description
`/v1/chat/completions`	POST	Main entry point. Streaming (`stream: true`) or JSON response.
`/v1/completions`	POST	Legacy alias; same handler as chat completions.
`/v1/models`	GET	Returns one model entry whose id is the `agent` param (or `helix-agent` when unset).
`/health`	GET	`{"status":"ok"}`.

Headers¶

The handler reads the optional X-Session-ID header from incoming requests and propagates it onto the exchange (useful for agent memory).

Headers set on the exchange before invoking the downstream processor:

Header	Description
`openai.model`	The model id from the request body.
`openai.stream`	The request's `stream` flag (bool).
`Content-Type`	`application/json`.

Multi-turn conversations are rendered as a plain-text transcript with [Conversation so far] / [Latest user turn — respond to this] sentinels before being placed on the exchange body — the downstream agent sees the full context without having to parse the OpenAI message array.

Examples¶

Expose a Helix agent under :8080 and let Cursor / Continue.dev talk to it:

- id: agent-front
  from: openai-server://0.0.0.0:8080?agent=my-research-agent&api_key=${MY_TOKEN}
  steps:
    - agent:
        type: react
        model: openai://chat?model=gpt-4o
        tools: [...]

A pre-canned echo route for local development (no agent needed — any processor works):

- id: echo
  from: openai-server://localhost:8081
  steps:
    - setBody:
        starlang: |
          %sl 2.0
          output text/plain
          input payload
          ---
          "You said: " ++ payload

Hitting GET /v1/models then returns:

{"object":"list","data":[{"id":"helix-agent","object":"model","owned_by":"helix","created":1717500000}]}

Behavior notes¶

CORS open by default — Access-Control-Allow-Origin: * so browser-side OpenAI clients (Open WebUI, etc.) work out of the box.
Streaming preserves every byte including newlines and tabs; earlier versions used strings.Fields() which collapsed markdown tables, that bug is fixed. Streaming sends 32-byte chunks every 5 ms.
Token usage is approximated. The non-streaming JSON response sets usage.prompt_tokens = len(text) / 4 and matching completion tokens. If the downstream agent surfaces real token counts via headers, consider replacing the body with a JSON envelope before responding.
Authentication is a single shared bearer token — no key rotation, no per-tenant keys. Put this behind a proper API gateway for production.
Server lifecycle follows the route lifecycle. Stopping the route triggers http.Server.Shutdown(ctx).
Panic recovery wraps the handler — a panic returns a 500 with a structured error response rather than dropping the connection.

Source¶

pkg/component/openaiserver/server.go

openai-server://¶