To configure a custom provider in Hermes Agent, set the main model’s provider to custom, supply the provider’s model identifier and OpenAI-compatible base_url, and keep the credential in ~/.hermes/.env (or the process environment). For an auxiliary task, put the endpoint directly in that task’s block: a task-level base_url takes precedence over provider.
Antihost offers VPS plans with one-click Hermes Agent, NVMe storage and a 14-day free trial.
What Hermes means by a custom provider
Hermes Agent can send requests to services that expose the API shape expected by its selected transport. A custom provider is useful when the model is hosted by a service not represented by Hermes’s named provider list, when an organization exposes an internal gateway, or when inference runs on a machine you control. The essential pieces are always the same:
As an Amazon Associate I earn from qualifying purchases.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →- A model identifier that the endpoint recognizes.
- An OpenAI-compatible API base URL, including the API prefix required by that server.
- A credential accepted by that endpoint, unless the server is intentionally unauthenticated on a trusted local network.
- A Hermes configuration location that matches the job: the top-level
modelblock for the main agent, orauxiliary.<task>for a supporting task such as vision.
Hermes separates behavior from secrets. Put routing, model names, and fallback policy in ~/.hermes/config.yaml. Put API keys in ~/.hermes/.env or inject them through the process environment. This keeps credentials out of the YAML file you are more likely to back up or share.
Configure the main Hermes model
1. Create or open the Hermes configuration files
The user-level files are:
~/.hermes/config.yamlfor non-secret settings.~/.hermes/.envfor user-managed secrets and other environment values.
Create the directory first if it does not exist, then ensure the account running Hermes can read both files. The process environment is also valid for secrets; the .env file is simply the usual persistent location documented by Hermes.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
2. Put the provider key in the environment file
# ~/.hermes/.env
CUSTOM_PROVIDER_API_KEY=your-keyReplace your-key with the key issued by the service. Do not commit this file to source control or paste the key into a shared configuration example. If your deployment injects secrets through a service manager or container, define the same variable there instead.
3. Add a top-level custom model block
# ~/.hermes/config.yaml
model:
provider: custom
default: my-model
base_url: https://provider.example/v1
api_key: ${CUSTOM_PROVIDER_API_KEY}For a custom OpenAI-compatible endpoint, provider: custom belongs in the top-level model: section. The default value is the model identifier sent to the service. Change my-model to the exact identifier advertised by your provider; names are not interchangeable across services.
base_url is the API root Hermes uses for the main model. Many servers expect an OpenAI-style /v1 suffix, as shown above. If the provider documents a different prefix, use that exact path rather than appending /v1 automatically.
The api_key value uses Hermes’s environment substitution syntax. At startup Hermes replaces ${CUSTOM_PROVIDER_API_KEY} with the value from the environment. If the variable is missing, the placeholder remains literally in the configuration and Hermes logs a warning; it does not silently discover a key under another variable name.
4. Verify the model identifier and endpoint together
A valid URL with an invalid model name still fails. Check the provider’s model list or service documentation and copy the identifier exactly, including punctuation, capitalization, and any namespace. Then check that the base URL is the endpoint root expected by the Hermes transport. A server that exposes only a vendor-specific protocol will not work merely because it has a URL; it must implement the API shape Hermes is configured to call.
5. Start Hermes and test a small request
Run Hermes in the same user or service context that owns the configuration. A quick request is preferable to a long agent run because authentication, URL construction, and model selection errors appear immediately. If startup reports that the environment variable is unresolved, fix the environment first; changing YAML routing cannot compensate for a missing secret.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
What each main-model setting does
| Setting | Purpose | What to check |
|---|---|---|
model.provider |
Selects the provider family for the main agent. | Use the literal value custom for a custom OpenAI-compatible endpoint. |
model.default |
Names the model Hermes requests. | Use the exact identifier recognized by the endpoint. |
model.base_url |
Sets the main model’s API root. | Include the required path, commonly /v1. |
model.api_key |
Supplies the credential to the selected transport. | Prefer ${VARIABLE} and define that variable in ~/.hermes/.env or the process environment. |
Keep these keys at the top-level model mapping for the primary agent. Putting them under an auxiliary task changes which request uses the endpoint; putting an auxiliary-only key in the main block does not configure that task.
Route an auxiliary task to a custom endpoint
Supporting jobs can use their own model and server. Hermes documents a direct endpoint pattern for an auxiliary task such as vision:
auxiliary:
vision:
base_url: http://localhost:1234/v1
api_key: local-key
model: qwen2.5-vlIn this form, Hermes routes the vision task to http://localhost:1234/v1, authenticates with local-key, and requests qwen2.5-vl. Use the identifier and credential appropriate for your server; the values above are an example configuration shape.
Why base_url wins
For an auxiliary task or provider block, a configured base_url takes precedence over provider. Hermes uses that endpoint directly and ignores the provider selector for routing. This is the most explicit way to send one task to a particular service, and it prevents an inherited provider name from redirecting the request somewhere else.
The task can use its own api_key. If that key is omitted, Hermes can fall back to OPENAI_API_KEY for the direct custom endpoint. It does not reuse OPENROUTER_API_KEY to authenticate an unrelated custom endpoint. Define a provider-specific variable when the endpoint has its own credential rather than relying on a key intended for another service.
Match the model to the task
The endpoint must support the operation Hermes is asking it to perform. A vision task requires a multimodal model and a server that accepts the corresponding image input; a text-only model cannot be made multimodal by changing the YAML name. Likewise, the server must implement the request and response fields expected by Hermes’s selected transport, not merely provide a chat interface with a superficially similar URL.
Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
Use environment substitution safely
Hermes supports ${VAR_NAME} substitution in config.yaml. You can keep both the URL and key outside the file:
model:
provider: custom
default: my-model
base_url: ${CUSTOM_PROVIDER_BASE_URL}
api_key: ${CUSTOM_PROVIDER_API_KEY}# ~/.hermes/.env
CUSTOM_PROVIDER_BASE_URL=https://provider.example/v1
CUSTOM_PROVIDER_API_KEY=your-keyThis arrangement is useful when the same configuration is deployed to multiple environments. Each environment can provide a different endpoint without editing the YAML. It also makes it clear which values are secrets and which are ordinary routing settings.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →When substitution fails, Hermes leaves the placeholder unchanged and logs a warning. Treat that warning as a configuration error, not as a provider outage. Check all of the following:
- The variable name in YAML exactly matches the name in
~/.hermes/.env, including capitalization and underscores. - The file is in the home directory of the account running Hermes.
- The process was restarted after changing the environment.
- The resulting URL is a complete endpoint rather than a literal string such as
${CUSTOM_PROVIDER_BASE_URL}.
Connect local and self-hosted servers
Hermes documents local OpenAI-compatible servers under names such as ollama, vllm, and llamacpp. A local server can be addressed with a URL such as http://127.0.0.1:11434. When you provide a bare host and port, Hermes adds /v1 automatically for this local-provider pattern. If your server already requires a complete path, specify that path explicitly and confirm it with the server’s documentation.
For a local main model, the same custom-provider structure applies:
model:
provider: custom
default: local-model-name
base_url: http://127.0.0.1:11434/v1
api_key: ${LOCAL_MODEL_API_KEY}Some local installations accept a placeholder key because they do not authenticate loopback traffic. Others enforce a token. Use the value your server expects, and do not assume that a hosted provider key belongs in a local configuration.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
For a local auxiliary service, keep the task-specific block separate:
auxiliary:
vision:
base_url: http://localhost:1234/v1
api_key: local-key
model: qwen2.5-vlBefore blaming Hermes, verify that the local server is running, listening on the address reachable from the Hermes process, and exposing the expected API path. If Hermes runs in a container, 127.0.0.1 refers to that container, not necessarily the host machine; use the network address that is reachable from the containerized process.
Hosted custom endpoint versus local endpoint
| Decision axis | Hosted custom provider | Local or self-hosted server |
|---|---|---|
| Credential source | Provider-issued key, commonly injected through a named environment variable. | A local placeholder key, a self-hosted token, or no key if the server is configured without authentication. |
| Endpoint compatibility | The service must expose the OpenAI-compatible path and transport Hermes expects. | The local server must expose the same compatible API and be reachable from the Hermes process. |
| Data path | Requests travel to the hosted service. | Inference can remain on infrastructure you control, subject to that infrastructure’s network and logging configuration. |
| Operational work | Requires an account, billing arrangement, network access, and valid credentials. | Requires downloading models, suitable hardware, a running server, and enough capacity to keep it available. |
| Failure handling | A YAML fallback can move the main agent to another configured provider if the primary fails. | The fallback should account for the possibility that the local process or host is offline. |
These are operational differences, not separate Hermes configuration mechanisms. In both cases, the model name, URL, credential source, and API compatibility must agree.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Configure a fallback provider
Primary fallbacks are defined in config.yaml; Hermes provides no environment-variable equivalent for the fallback chain. A current configuration uses fallback_providers:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsfallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4The list describes the provider and model Hermes should try when the primary model cannot serve a request. Add the fallback policy to the same configuration environment as the main model, and make sure every fallback has the credentials and network access it needs.
An older single fallback_model shape remains backward-compatible, but new configurations should use fallback_providers. A fallback does not repair an invalid primary URL or missing key; it only gives Hermes another configured route to try. If the YAML itself is malformed, neither the primary nor the fallback can be loaded.
Use the interactive model selector
Hermes provides the hermes model command for interactive provider and model selection. This is useful when you prefer a guided prompt over editing the model fields manually. Follow the selector’s prompts to choose the provider and model, then inspect the resulting YAML so you can confirm the endpoint and credential source.
The auxiliary-model picker persists its choices under the relevant auxiliary.<task>.* keys in config.yaml. After using the picker, check that the task has the intended base_url, model, and key behavior. If a direct base_url is present, remember that it controls routing even if another provider name is also stored in that block.
Recommended Free Tools
Troubleshoot a custom-provider failure
Hermes says the model or provider is unknown
- For the main agent, confirm the mapping is named
modeland containsprovider: custom. - For an auxiliary job, confirm the keys are under the exact task path, such as
auxiliary.vision. - Check indentation and spelling in YAML; a correctly spelled key at the wrong nesting level is still ignored.
The request goes to the wrong service
- Look for a task-level
base_url. It overrides the provider selector for that task. - Check whether an interactive selection rewrote the relevant
auxiliary.<task>.*keys. - Print or inspect the effective configuration without exposing the secret, and verify the final URL includes the required API prefix.
Authentication fails
- Confirm the key variable exists in the environment seen by the Hermes process, not only in your interactive shell.
- Make sure the placeholder name in YAML exactly matches the variable name.
- For a direct custom endpoint, provide its own
api_keyor useOPENAI_API_KEYwhen that is the intended fallback. - Do not expect
OPENROUTER_API_KEYto authenticate a separate custom endpoint. - Check that the key belongs to the endpoint’s account and has permission to use the requested model.
The URL is rejected or returns a protocol error
- Confirm the server implements the OpenAI-compatible API shape required by Hermes’s transport.
- Try the documented path with and without
/v1only when the server documentation distinguishes those forms; do not append paths at random. - For local services, verify the listener address from the same network namespace as Hermes.
- Check that TLS, proxy, and firewall settings permit the connection to a hosted endpoint.
The task works but produces an unsupported result
Check model capability rather than routing. A vision task needs a multimodal model, while a text-only model may answer ordinary prompts but fail when Hermes supplies image input. Select a model that supports the task and confirm the server exposes that capability through the compatible API.
The primary provider fails intermittently
Add a fallback_providers list in config.yaml, then verify each fallback’s credentials independently. The fallback chain is configuration-only; placing a fallback name in an environment variable does not enable it.
Security and maintenance checklist
- Keep API keys in
~/.hermes/.envor an equivalent secret store, not in examples committed to a repository. - Restrict permissions on the environment file so only the Hermes account can read it.
- Use separate variables for separate providers and tasks when credentials differ.
- Do not log complete authorization headers or print the contents of the environment file while debugging.
- Record the model identifier and endpoint path with the deployment configuration so a later change does not silently route requests elsewhere.
- When changing a model server, test both authentication and task capability; a successful HTTP connection alone does not prove that the selected model can perform the job.
- Review fallback entries whenever a provider, model name, key, or network boundary changes.
Complete configuration patterns
Hosted custom main model with environment substitution
# ~/.hermes/config.yaml
model:
provider: custom
default: my-model
base_url: ${CUSTOM_PROVIDER_BASE_URL}
api_key: ${CUSTOM_PROVIDER_API_KEY}
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4# ~/.hermes/.env
CUSTOM_PROVIDER_BASE_URL=https://provider.example/v1
CUSTOM_PROVIDER_API_KEY=your-keyThis pattern keeps both the endpoint and credential outside the YAML while retaining a config-file fallback chain.
Direct local auxiliary model
auxiliary:
vision:
base_url: http://localhost:1234/v1
api_key: local-key
model: qwen2.5-vlBecause base_url is present in the task block, Hermes routes this vision task directly to the local server regardless of any provider selector stored alongside it.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Final preflight before running an agent
- Identify whether the setting belongs in the top-level
modelblock or anauxiliary.<task>block. - Copy the provider’s exact model identifier into
defaultfor the main model ormodelfor an auxiliary task. - Set an OpenAI-compatible
base_urlwith the required API prefix. - Place the key in
~/.hermes/.envor the process environment and reference it with${VAR_NAME}when appropriate. - Check that no unresolved placeholder remains and that the process can read the environment file.
- For auxiliary routing, verify that a task-level
base_urlis intentional because it overridesprovider. - Confirm the selected model supports the task, especially multimodal work.
- Add and test a
fallback_providerschain if continued operation matters when the primary endpoint is unavailable. - Run a small request before starting a long workflow.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
