Custom Gateway
Compose a ChatJS app with a third-party gateway registry item
Install a custom gateway when creating your app. If your endpoint implements the OpenAI API, you can also use the built-in OpenAI Compatible gateway.
chat-js create my-chat --gateway https://example.com/r/my-gateway.json
chat-js create my-chat --gateway ./my-gateway.jsonRemote registry items and their dependencies require HTTPS. HTTP is supported for loopback development servers only.
Author a registry item
Start from a built-in item in the gateway registry. The authoring contract describes the complete metadata and adapter interface.
Your root item must use type: "registry:item". Declare its SDK in dependencies, and include an adapter exporting Gateway at ~/lib/ai/gateway.ts. Supporting files belong under ~/lib/ai/gateway/ and can come from registryDependencies.
Set meta.chatjs with:
kind: "gateway",contractVersion: 1, and a unique literalid.capabilitiesdescribing image and video support.- Complete
defaultsfor models, workflows, documents, and tools. Use model IDs served by your endpoint. envRequirements, an array of required groups. Each group’soptionscontains alternative sets of variables.optionalEnvfor additional variables the adapter reads.
For example, an endpoint that requires a base URL and accepts an optional API key can declare:
{
"envRequirements": [{ "options": [["MY_GATEWAY_BASE_URL"]] }],
"optionalEnv": ["MY_GATEWAY_API_KEY"]
}This is a metadata fragment, not a complete registry item. Read declared credentials through the adapter’s injected environment, such as this.env.MY_GATEWAY_API_KEY when extending GatewayRuntime from @chat-js/gateways/runtime.
Generated app
The CLI installs the selected adapter and dependencies, then writes lib/ai/gateway-model-defaults.ts with the gateway ID, defaults, capabilities, and environment declarations. lib/env.ts forwards those declared variables to the adapter, and scripts/check-env.ts checks the requirements. You do not add gateway entries to a central application registry or environment schema.
The generated chat.config.ts selects your gateway. Add credentials to .env.local, then verify the app:
bun test:types
bun fetch:models
bun devSend a real chat message to verify provider authentication and streaming. Type checks validate the adapter interface and configuration, but cannot verify remote credentials or model availability.