An agent is more useful when it can keep working after you close your laptop. Hosting Hermes gives it a place to keep its conversations, configuration, and skills, and a gateway through which you can reach it from a chat platform.
Hermes Agent is an open-source agent from Nous Research. You bring the model credentials; Hostless runs the deployment. You can start with the Marketplace service or use Apps when you need to own the container and its configuration.
Choose your deployment path
| Use | When it fits |
|---|---|
| Marketplace service | You want Hostless’s packaged Hermes deployment, generated dashboard credentials, and persistent storage. |
| Apps | You need a custom image, dependencies, startup configuration, or authentication setup, and can maintain those choices. |
Use Marketplace for the packaged setup. Apps gives you control, but it also makes the image, storage permissions, authentication, and upgrades your responsibility.
You will need a Hostless account and project, a supported model-provider API key, and optionally a bot token for the chat platform you want to connect. Hosting and model usage are separate costs: Hostless runs the service, while your model provider bills usage against your key. Check your provider’s current model availability, limits, and pricing before choosing a model.
1. Select Hermes in Marketplace
Open the Hostless dashboard, select your project, and open the Marketplace service creation flow. In Select service, choose Hermes, then continue to Configure.
Give the service a descriptive name, such as my-hermes-agent. Supply one provider key: OpenRouter, OpenAI, or Anthropic. Although each individual field is optional, the service requires at least one of them.
Supply only the key for the provider you intend to use. When several keys are supplied, the packaged deployment chooses OpenRouter first, then OpenAI, then Anthropic.
Choose the Model deliberately. The default model comes from the OpenRouter list; entering an OpenAI or Anthropic key does not automatically replace that model with one compatible with your provider. Confirm that the selected model is available to your account and supports the agent’s tool use. If the form does not offer a compatible choice, resolve that before deployment.
2. Add a chat channel, if you want one
The service exposes these optional settings:
| Channel | Configuration fields |
|---|---|
| Telegram | TELEGRAM_BOT_TOKEN |
| Slack | SLACK_BOT_TOKEN and SLACK_APP_TOKEN for Socket Mode |
| Discord | DISCORD_BOT_TOKEN |
Create the bot or application with the chat provider first. Follow the Hermes messaging documentation for the channel’s permissions, pairing, and allowed-user configuration. A token supplies credentials; it does not replace the provider’s setup or decide who should be allowed to use your agent.
Start with one channel so you can verify it before adding another. Keep tokens in configuration fields, out of Git, screenshots, and chat messages.
3. Review and deploy
Continue to Review & deploy. Check the name, provider, model, optional channels, and estimated hosting cost before submitting.
The packaged service runs the nousresearch/hermes-agent image with gateway run. It attaches a 5 GiB persistent volume at /opt/data and runs one replica. Hermes stores configuration and agent state in that directory; the container’s temporary filesystem is not the place for files you need to keep.
Follow the service’s deployment progress. If deployment fails, read the first useful error before retrying. An image startup error, a volume problem, and an invalid model key need different fixes.
4. Open the dashboard and test the agent
Once the service is ready, open its dashboard URL from the service details. Connection information includes Dashboard Username and Dashboard Password. The packaged username is admin; the password is generated for that deployment.
Check dashboard authentication before public use. The packaged service uses password authentication. Current Hermes Docker guidance recommends OAuth through Nous Portal or self-hosted OIDC for public deployments. Confirm that your deployment meets that guidance before putting sensitive credentials or tools behind its dashboard; use a custom setup when you need those authentication controls.
Send a small test message through the configured channel, for example:
Reply with a short checklist for reviewing a pull request. Do not run commands or access external services.
Confirm that the agent responds and the logs show no provider or channel errors. A ready container alone does not prove that model credentials work.
The Marketplace URL routes to the dashboard on port 9119, and the service’s TCP health check uses that same port. Open the supplied HTTPS URL in your browser; you do not need to add :9119 to it. It does not expose the separate OpenAI-compatible API on port 8642. Do not append /v1/chat/completions to the dashboard URL and expect an API endpoint.
When to use Apps instead
Choose Apps if you want to maintain a custom Hermes deployment in Git. Follow the GitHub-to-Hostless guide for connecting the repository and choosing Docker builds.
A custom deployment needs these decisions before it is ready to run:
- Image and startup: Use the official image as your starting point, pin a tested version or digest, and preserve its entrypoint. The documented gateway invocation is
gateway run. Bake additional dependencies into your image rather than installing them on every agent turn. - Persistent storage: In the app’s Storage step, create or select a persistent volume and set its mount path to
/opt/data, replacing the default path. Keep the app at one replica. Never run two gateways against the same Hermes data directory. - Configuration and permissions: Initialize
config.yamlon the mounted volume, with a provider and model that match your credentials. Ensure the image’s runtime user can write there. Mounting a volume hides files baked into the image at the same path, so copying configuration into/opt/dataduring the Docker build is not sufficient. - Secrets: Add provider and channel credentials through environment settings. Keep them out of the Dockerfile and repository. Supply separate generated secrets for whichever authentication scheme you enable.
- Dashboard access: If exposing the dashboard, configure a supported public authentication provider, bind to
0.0.0.0, setHERMES_DASHBOARD_PORT=8000to match Hostless Apps’ default exposed port and injectedPORT=8000. SettingPORTalone does not configure Hermes’s dashboard listener. Follow the upstream instructions for public URLs and trusted reverse proxies. - Health checks: Choose a check that works with authentication enabled. The packaged service uses a TCP check on the dashboard port; an unauthenticated request to a protected page can return
401while the service is listening normally.
Port configuration: Apps and Marketplace are different
For a custom App, use the default Hostless application port, 8000. Configure the Hermes dashboard explicitly:
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_PORT=8000
These are listener settings, not a complete deployment configuration; the dashboard also requires the authentication setup described above. Hostless supplies PORT=8000 for a default App, but Hermes needs its own HERMES_DASHBOARD_PORT setting. A Dockerfile’s EXPOSE instruction does not remap a listener from 9119 to 8000. If you declare it in your custom image, use EXPOSE 8000, and ensure the health check targets port 8000.
The Marketplace service configures its own networking and keeps the dashboard on 9119. You do not need to change its port to 8000.
| Deployment | Dashboard listener | Hostless routing target | Browser access |
|---|---|---|---|
| Custom App with default settings | 0.0.0.0:8000 |
8000 |
Supplied HTTPS URL |
| Hermes Marketplace service | 0.0.0.0:9119 |
9119 |
Supplied HTTPS URL |
Hermes’s API on 8642 is separate. The Marketplace does not expose it through the dashboard URL, and configuring an App to route to the dashboard on 8000 does not expose the API either.
The official image also has startup and filesystem requirements that a generic application container may not satisfy. Validate those against Hostless’s runtime before treating a Dockerfile as deployable. Marketplace supplies Hermes-specific initialization and security settings; selecting Docker in Apps does not automatically reproduce them.
Use the official Docker guide alongside the Hostless app configuration reference. Test image startup, volume ownership, authentication, and a real agent response before relying on a custom instance.
Keep the agent useful across deployments
After the first successful conversation, save a harmless preference, restart the service, and check that the agent can still retrieve it. This checks the storage path you depend on rather than just the deployment’s status.
Keep a recoverable backup of important agent data before upgrades. Persistent storage survives container replacement, but it is not a backup. Keep one gateway writing to that data directory, and check the implications before detaching or deleting storage.
If you customize Hermes configuration, verify it after a restart. The packaged service initializes config.yaml from its service settings when the deployment starts, so direct edits to that file should not be treated as durable configuration overrides.
Troubleshooting
| What you see | What to check |
|---|---|
| Provider key required | Supply at least one supported provider key. |
| Model not found or authentication fails | Match the model to the selected provider and confirm access with that provider. |
| Agent does not reply in chat | Check bot credentials, channel permissions, pairing or allowed users, and gateway logs. |
| Dashboard asks for credentials | Read the deployment’s generated connection information. |
| API client fails at the dashboard URL | The Marketplace dashboard and internal API use different ports; the public dashboard URL is not the API base URL. |
| State disappears after a deployment | Verify the /opt/data mount and that Hermes writes its state there. |
| Custom app never becomes healthy | Check startup logs, volume permissions, listening address, exposed port, and whether the probe requires authentication. |
Start with one provider, one channel, and a small task. Once the conversation works and state survives a restart, add the skills and integrations your agent needs.
Comments