How to use Telnyx AI Inference with Hermes Agent

The Telnyx integration is a vendor-maintained external Hermes model-provider plugin. It connects Hermes to the OpenAI-compatible Telnyx Chat Completions API, supports streaming and tool calling, and retrieves the models available to your Telnyx account.

Primary references

By the end of this guide, you will have:

The Telnyx provider is currently available as the prerelease:

The release was published from commit:

It was validated against:

The release supports Python 3.11–3.13. Release candidates currently track the Hermes main branch. Stable v0.1.0 is expected to pin the first released Hermes version that automatically routes plugins declared as kind: model-provider into the correct discovery directory.

References:

Hermes discovers external model providers under:

The default location is:

The current generic plugin installer initially clones plugins into:

For this release, you must therefore move the installed Telnyx plugin into the model-providers subdirectory. This manual step should become unnecessary after Hermes ships provider-aware installation routing.

References:

You need:

Hermes supports command-line installation on Linux, macOS, WSL2, native Windows, and Android through Termux. The standard installer manages Python, Node.js, the Hermes virtual environment, and other application dependencies.

References:

Skip this step when Hermes is already installed and hermes doctor completes successfully.

Run the official installer:

Reload the shell after installation:

For Zsh:

References:

For a headless environment that does not need browser automation:

Reference: Hermes headless installation options

Open PowerShell and run:

References:

Run:

You can also check the installed CLI:

The normal per-user installation stores Hermes under:

The standard per-user layout includes:

References:

Sign in to the Telnyx Mission Control Portal.

Open the API Keys section:

https://portal.telnyx.com/#/app/api-keys

Then:

Telnyx only displays the complete key at creation time.

References:

Do not:

Telnyx recommends storing API keys in environment variables or a secrets manager, separating development and production credentials, and rotating keys periodically.

Reference: Telnyx authentication security practices

Two installation paths are available.

This is the simplest path and follows the plugin repository’s primary instructions.

Run:

The installer reads the plugin manifest, detects the required TELNYX_API_KEY, prompts for it using a masked input, and saves the value to:

The installer may also ask:

That general plugin toggle does not activate or deactivate a model-provider plugin. Model providers are activated by selecting them through hermes model or by passing --provider telnyx when launching a session.

References:

On Linux, macOS, or WSL2:

The resulting location should be:

References:

On native Windows PowerShell, use the equivalent directory move:

The Windows command uses the same Hermes home and provider-discovery paths described by the plugin and Hermes documentation.

References:

This option pins the installation to v0.1.0-rc.1 instead of cloning the changing main branch.

On Linux, macOS, or WSL2:

The provider will be installed at:

References:

On native Windows PowerShell:

List the provider directories:

You should see either:

or:

depending on the installation method.

Inspect the plugin manifest:

For the pinned Git path:

The manifest should declare:

It should also declare TELNYX_API_KEY as a required secret.

Reference: Telnyx provider manifest

Skip this step if the plugin installer already prompted for and saved the key.

The provider reads:

The normal Hermes environment file is:

Add the following entry:

References:

Alternatively, expose the key to the current process as an environment variable:

An environment variable set only in an interactive shell will not automatically be visible to a separately managed gateway service. For a persistent Hermes setup, storing the key through the plugin installer or in the active profile’s .env file is the preferred current path.

Hermes profiles have separate home directories and separate .env files. Install the provider and configure the key in the same profile that will use Telnyx.

Reference: Hermes profiles and isolated configuration

On Linux, macOS, or WSL2:

Do not print the complete key in diagnostics or commit .env to source control.

Reference: Telnyx API-key security practices

Hermes discovers and registers model providers once per running process. Restart a long-running gateway after installing or updating the provider:

Check its state:

References:

A restart is not required before starting a new short-lived CLI process because that new process performs fresh provider discovery.

Reference: Hermes model-provider discovery lifecycle

Run the full provider-selection wizard from your terminal:

Do not run this command inside an active Hermes chat session.

In the picker:

hermes model is the complete provider setup command. It can discover providers, prompt for API keys, retrieve provider-specific model lists, and save the selected provider and model into Hermes configuration.

References:

The Telnyx provider retrieves the live model catalog from:

The endpoint requires bearer authentication and returns the models available to the authenticated Telnyx account.

References:

The current curated fallback models are:

References:

The provider’s recommended default starting point is:

The complete launch combination is:

Hermes keeps provider and model as separate command-line values, so the model is not prefixed with telnyx/ when passed through -m or --model.

Reference: Telnyx provider usage examples

Run a noninteractive test that explicitly selects Telnyx:

Expected response:

The -z or --oneshot mode accepts one prompt and prints only the final response. The --provider and --model flags override the configured provider and model for that invocation without changing the global configuration.

References:

You can test a different Telnyx model:

Launch a new Hermes chat that explicitly uses Telnyx:

You can also start Hermes using its shorter default command after selecting Telnyx through hermes model:

References:

A useful first prompt is:

The Telnyx Chat Completions API supports tool and function calling, and the provider’s curated fallback models were verified with tool-using conversations.

References:

Inside a Hermes session, ask the model to perform a low-risk tool task, such as:

Review the proposed tool call before approving any operation that changes files, sends messages, accesses credentials, or modifies external systems.

Complete this step only when Hermes will run through Telegram, Discord, Slack, or another persistent channel.

First, confirm that ordinary CLI chat works. Hermes recommends establishing one clean conversation before adding gateway, cron, voice, or routing features.

Reference: Hermes quickstart

Configure the Gateway:

Restart it after configuration:

Check its status:

References:

The Gateway must run under the same Hermes profile in which the Telnyx provider and API key were installed.

Reference: Hermes profiles

Hermes model-provider plugins describe an inference backend that Hermes can use for its main and auxiliary model calls. Third parties can add providers by placing a plugin directory under:

The Telnyx package registers a provider profile through Hermes’s documented providers.register_provider interface.

References:

The provider uses the OpenAI-compatible Telnyx base URL:

Telnyx’s Inference API supports OpenAI-compatible chat completions, streaming responses, model listing, and function calling.

References:

The provider uses two catalog sources:

The live catalog is filtered to text-generation workloads. It accepts both text-generation and text generation task labels because both forms have appeared in the Telnyx catalog.

Reference: Telnyx provider model-discovery implementation

The current Hermes plugin installer places the repository in the generic plugins directory. Model-provider discovery scans the model-providers subdirectory, so the manual move is currently required.

Reference: Telnyx provider installation limitation

The following in-session path may currently report that telnyx is an unknown provider:

Until Hermes’s generic external-provider resolver is updated, use one of these supported paths:

or:

or:

References:

Telnyx catalog prices are expressed per one million tokens using:

Until Hermes ships generic handling for this tagged pricing unit, treat Hermes’s displayed or exported cost estimate for Telnyx as unavailable or non-authoritative.

Use current Telnyx pricing sources for billing decisions.

References:

The provider does not volunteer a default output-token cap. The plugin repository reports that combining explicit max_tokens or max_completion_tokens values with function tools can cause Telnyx error 10015 on some hosted models.

Leave Hermes’s explicit maximum-token setting unset unless the workflow requires it and the selected model has been tested with tools.

Reference: Telnyx provider output-cap constraint

Confirm that the plugin is inside the model-provider directory:

The provider must not remain only at:

It must be under:

Restart any running Gateway:

Then rerun:

References:

Check that TELNYX_API_KEY exists in the active Hermes profile:

Do not print the complete value.

A 401 response normally means that bearer authentication is missing or invalid.

Verify that:

References:

The provider is probably displaying its curated fallback catalog because the authenticated live model request failed.

Check:

The fallback catalog currently includes:

References:

Restart it:

Then check:

Provider registration happens once per process, so a Gateway started before installation will not see the newly added provider until it restarts.

References:

Exit the active session:

Then run:

Alternatively, launch a new session with explicit flags:

Reference: Telnyx provider known constraints

Launch a Telnyx session explicitly:

To change the saved default, exit the session and run:

hermes model is the complete provider setup wizard. The /model command inside a conversation is intended only for switching among providers Hermes can already resolve.

References:

Run Hermes diagnostics:

Then test a direct one-shot conversation:

For a Gateway deployment, also run:

Hermes recommends the following recovery sequence:

Reference: Hermes recovery toolkit

Remove any custom agent.max_tokens configuration and retry.

The current provider deliberately does not set a default output cap because some Telnyx-hosted models reject explicit output-token parameters when tools are included.

Reference: Telnyx provider known constraints

The current repository recommends updating the provider through Git.

For an installation at telnyx-provider:

For an installation at telnyx:

Restart the Gateway after updating:

Then run:

and complete a one-shot verification:

Reference: Telnyx provider update instructions

For production use, review the target release and pin an explicit tag rather than automatically tracking a changing main branch.

First, use hermes model to select another provider so Hermes retains a working default:

Remove the provider directory.

For the installer-and-move path:

For the Git-clone path:

Restart the Gateway:

Remove the Telnyx API key from:

when it is no longer required by another Telnyx integration.

References:

The Telnyx provider executes inside the Hermes process. Install it only from the official Telnyx-owned repository and review its release before upgrading.

The plugin repository is:

https://github.com/team-telnyx/hermes-inference-provider

The current release is:

https://github.com/team-telnyx/hermes-inference-provider/releases/tag/v0.1.0-rc.1

The package is distributed under the MIT License:

https://github.com/team-telnyx/hermes-inference-provider/blob/main/LICENSE

Report security issues through the repository’s private GitHub Security Advisory flow rather than opening a public issue.

Reference: Telnyx provider security guidance

After Telnyx inference is working, you can:

Hermes distinguishes between a main model and auxiliary model slots. The main model handles user messages, streamed responses, and tool-call loops. Auxiliary slots handle smaller tasks such as context compression, image analysis, webpage summarization, approval scoring, MCP tool routing, title generation, and skill search. Each auxiliary slot can be configured independently.

The current Telnyx STT and TTS repositories contain tested provider implementations intended for contribution to Hermes core; they are not currently distributed as standalone end-user plugins but coming soon.

The current Telnyx inference-provider release also documents an outstanding external-provider resolver limitation. Until the related provider-neutral Hermes changes land, use Telnyx as the main provider through hermes model or the --provider telnyx launch option rather than promising task-specific auxiliary-provider selection.