DEV Community

Charan Gutti
Charan Gutti

Posted on

🌍 Exposing Your Hermes Agent to the Internet with Tailscale Funnel (Safely)

#ai #webdev #agents #hermes

Run your local Hermes Agent anywhere, then securely expose it to your backend without renting a VPS or configuring Nginx.

One of the coolest things about Hermes Agent is that it exposes an OpenAI-compatible API server.

That means your backend, frontend, mobile app, or even another AI agent can communicate with Hermes exactly like it would communicate with OpenAI.

But there's one problem...

Hermes usually runs on your local machine:

http://127.0.0.1:8642
Enter fullscreen mode Exit fullscreen mode

That works great for local development.

It doesn't work when:

  • your backend is deployed on Vercel
  • your API lives on Railway
  • your frontend is hosted on Netlify
  • your mobile app needs to call Hermes
  • your teammate wants to use your agent

So how do you expose it safely?

The answer is Tailscale Funnel.

🤔 What is Tailscale Funnel?

Most developers immediately think:

"I'll just port forward."

Please don't.

Opening ports on your home network is usually a bad idea.

Instead, Tailscale Funnel gives you:

  • HTTPS
  • automatic certificates
  • encrypted traffic
  • secure networking
  • no reverse proxy setup
  • no VPS required

Think of it as:

Your Computer
      │
      ▼
Tailscale
      │
      ▼
Public HTTPS URL
Enter fullscreen mode Exit fullscreen mode

Instead of exposing your machine directly to the internet, Tailscale securely publishes only the service you choose.

🏗 The Architecture

Here's what we're building.

                 Internet
                     │
                     ▼
      https://my-machine.ts.net
                     │
             Tailscale Funnel
                     │
                     ▼
        Hermes API Server (8642)
                     │
                     ▼
          Hermes Agent + Tools
Enter fullscreen mode Exit fullscreen mode

Your backend simply calls the HTTPS endpoint.

It never needs to know your local IP.

📦 Step 1 — Enable the Hermes API Server

Hermes includes a built-in OpenAI-compatible API server.

Open:

~/.hermes/.env
Enter fullscreen mode Exit fullscreen mode

Add:

API_SERVER_ENABLED=true

API_SERVER_KEY=my-super-secret-key

API_SERVER_PORT=8642

API_SERVER_HOST=127.0.0.1
Enter fullscreen mode Exit fullscreen mode

Let's understand each option.

API_SERVER_ENABLED

Turns on the API server.

API_SERVER_ENABLED=true
Enter fullscreen mode Exit fullscreen mode

API_SERVER_KEY

Protects your API.

API_SERVER_KEY=super-secret-key
Enter fullscreen mode Exit fullscreen mode

Every request must include:

Authorization: Bearer super-secret-key
Enter fullscreen mode Exit fullscreen mode

Never leave this empty.

API_SERVER_PORT

Default:

8642
Enter fullscreen mode Exit fullscreen mode

You can change it if another application is already using that port.

API_SERVER_HOST

Normally:

127.0.0.1
Enter fullscreen mode Exit fullscreen mode

Keep it this way when using Tailscale Funnel.

You do not need to bind Hermes to 0.0.0.0 just to use Funnel. Keeping it on localhost reduces unnecessary exposure.

🚀 Step 2 — Start Hermes

Start the gateway.

hermes gateway
Enter fullscreen mode Exit fullscreen mode

You should see something similar to:

API server listening on

http://127.0.0.1:8642
Enter fullscreen mode Exit fullscreen mode

Hermes is now running locally.

🧪 Step 3 — Test the API Locally

Before exposing anything, make sure Hermes works.

curl http://127.0.0.1:8642/v1/models \
  -H "Authorization: Bearer my-super-secret-key"
Enter fullscreen mode Exit fullscreen mode

If everything is configured correctly, Hermes should return the available model information.

Always test locally before exposing a service.

🌍 Step 4 — Install Tailscale

Install Tailscale on your machine.

Login:

tailscale login
Enter fullscreen mode Exit fullscreen mode

Verify:

tailscale status
Enter fullscreen mode Exit fullscreen mode

You should see your machine connected.

🌐 Step 5 — Create a Funnel

Now expose Hermes.

tailscale funnel 8642
Enter fullscreen mode Exit fullscreen mode

Or on some setups:

tailscale funnel --bg 8642
Enter fullscreen mode Exit fullscreen mode

Tailscale will generate something like:

https://my-computer.tailnet.ts.net
Enter fullscreen mode Exit fullscreen mode

Now your local Hermes API is securely reachable over HTTPS. Tailscale terminates TLS for you and forwards requests to your local service.

🔍 Verify the Funnel

Run:

tailscale funnel status
Enter fullscreen mode Exit fullscreen mode

You should see your public HTTPS URL and the local service it's forwarding to.

🔗 Your Backend Can Now Use Hermes

Instead of calling:

http://localhost:8642
Enter fullscreen mode Exit fullscreen mode

Use:

https://my-computer.tailnet.ts.net/v1
Enter fullscreen mode Exit fullscreen mode

Example:

const client = new OpenAI({
    apiKey: process.env.HERMES_API_KEY,
    baseURL: process.env.HERMES_URL
});
Enter fullscreen mode Exit fullscreen mode 
HERMES_URL=https://my-computer.tailnet.ts.net/v1

HERMES_API_KEY=my-super-secret-key
Enter fullscreen mode Exit fullscreen mode

Nothing else changes.

Because Hermes speaks the OpenAI API format, many existing OpenAI SDKs work by simply changing the baseURL.

🧩 Complete Flow 

Frontend

      │

      ▼

Backend

      │

      ▼

https://my-machine.tailnet.ts.net/v1

      │

      ▼

Tailscale Funnel

      │

      ▼

Hermes API Server

      │

      ▼

Hermes Agent

      │

      ▼

LLM Provider
Enter fullscreen mode Exit fullscreen mode

Your backend doesn't need SSH.

It doesn't need VPN software.

It simply makes HTTPS requests.

💻 Example Backend 

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.HERMES_API_KEY,
    baseURL: process.env.HERMES_URL
});

const response = await client.chat.completions.create({
    model: "hermes-agent",
    messages: [
        {
            role: "user",
            content: "Summarize today's meeting."
        }
    ]
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

Notice that this looks almost identical to using the OpenAI SDK—the only difference is the baseURL.

🎯 Real-World Use Cases

Personal AI Assistant 

Phone

↓

Backend

↓

Hermes at Home
Enter fullscreen mode Exit fullscreen mode

Your phone can interact with your personal AI wherever you are.

Portfolio Website 

Next.js

↓

Hermes

↓

Tools

↓

Terminal
Enter fullscreen mode Exit fullscreen mode

Your website can delegate tasks to Hermes without hosting the agent in the cloud.

Slack or Discord Bot 

Slack

↓

Backend

↓

Hermes
Enter fullscreen mode Exit fullscreen mode

The bot communicates with your local Hermes instance securely.

Mobile App 

Flutter

↓

Backend

↓

Hermes
Enter fullscreen mode Exit fullscreen mode

Perfect for testing AI features without deploying Hermes to a cloud VM.

🔐 Security Best Practices

Even though Funnel provides HTTPS, you should still secure your deployment.

✅ Always require an API key 

API_SERVER_KEY=...
Enter fullscreen mode Exit fullscreen mode

Never expose an unauthenticated API.

✅ Store secrets in environment variables 

.env

HERMES_URL=...

HERMES_API_KEY=...
Enter fullscreen mode Exit fullscreen mode

Avoid hardcoding secrets into your source code.

✅ Rotate API keys

If you suspect a key has been exposed, generate a new one and update your backend.

✅ Monitor logs

Review Hermes and Tailscale logs periodically to understand how your service is being used.

🚀 Tips

Keep Hermes on localhost

Prefer:

127.0.0.1
Enter fullscreen mode Exit fullscreen mode

instead of

0.0.0.0
Enter fullscreen mode Exit fullscreen mode

when using Funnel.

Use environment variables

Instead of:

apiKey: "abc123"
Enter fullscreen mode Exit fullscreen mode

Use:

apiKey: process.env.HERMES_API_KEY
Enter fullscreen mode Exit fullscreen mode

Verify locally first

If:

curl localhost:8642
Enter fullscreen mode Exit fullscreen mode

doesn't work,

Funnel won't fix it.

Always verify the local service before troubleshooting networking.

Treat Hermes like any production API

Use authentication, monitor access, and update your software regularly.

📚 Useful Resources

  • Hermes Agent API Server Documentation
  • Hermes Configuration Guide
  • Tailscale Funnel Documentation
  • Tailscale Serve vs Funnel Documentation
  • OpenAI SDK Documentation

🎯 Final Thoughts

One of the biggest advantages of Hermes is that it exposes a standard OpenAI-compatible API.

That means you can build your backend once and point it at:

  • OpenAI
  • OpenRouter
  • Ollama
  • LM Studio
  • Hermes Agent

with only a configuration change.

By combining Hermes with Tailscale Funnel, you can securely expose your local agent over HTTPS without managing reverse proxies or opening firewall ports.

For personal projects, prototypes, and even some production workflows, it's a simple and elegant way to make a local AI agent available anywhere while keeping your networking setup straightforward.

"The best infrastructure is often the one you don't have to think about."

Top comments (0)