Field notes · AI agents, Hermes & Claude Code By Julian Goldie

Hermes Agent SSH: Move The Agent's Terminal To A Remote Server In 6 Steps (2026)

One config change, two env lines and a hostname check. Here is the exact order, the keys that matter, and the gotchas that trip people on day one.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

Hermes agent ssh is one config change and two env lines: set terminal.backend to ssh, name the host and user, and the agent's shell work moves off your laptop and onto a server you control.

Here's how I'd set it up in six steps, using only the keys and commands in the official Hermes SSH backend reference.

The example running through every step is a two-person web studio with one Ubuntu VPS that hosts its client sites and a laptop where Hermes lives.

If you'd like a second pair of eyes on your server plan before you start, book a free SEO strategy session with my team.

Why Move The Terminal Off Your Laptop At All

Every Hermes install has one terminal backend, and it decides where shell commands execute.

The built-in list has six entries: local, docker, ssh, modal, daytona and vercel_sandbox, with Singularity and Sprites arriving as plugins.

On local, the agent works directly on the machine running Hermes, with no isolation at all.

On ssh, Hermes keeps running on the laptop while each command executes on the VPS.

The tools page flags the SSH option as recommended for security, because the agent can't modify its own code from there.

For the studio, that means the agent can tail logs and restart services on the VPS while its own install on the laptop stays untouched.

Keep one fact in mind from the start: the VPS is a real machine, not a sandbox, so anything the agent changes there stays changed.

Step 1: Prove Key Login Works Before Hermes Touches It

Open a normal terminal and run ssh ubuntu@your-vps with the key you plan to give Hermes.

If it asks for a password, stop and fix that first.

Hermes opens its link with BatchMode=yes, so there is nobody to answer a prompt.

The reference documents key auth only: either the file you name, or your system default key.

Write down three things for the next steps: the hostname, the login user and the port if it isn't 22.

Step 2: Flip The Backend To SSH

Run this once on the Hermes machine:

hermes config set terminal.backend ssh

That writes the choice into config.yaml, where it appears as terminal: with backend: ssh nested under it.

The quickstart lists the same command with the comment "Remote server".

Nothing connects yet, because Hermes still doesn't know where the server is.

Step 3: Put Host, User, Port And Key In The Env File

Connection details belong in ~/.hermes/.env, not in config.yaml.

For the studio's VPS, the file gets these lines:

TERMINAL_SSH_HOST=vps.studio-example.com
TERMINAL_SSH_USER=ubuntu
TERMINAL_SSH_PORT=22
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Only the first two are required.

The port falls back to 22 and the key falls back to your system default, so drop those lines if the defaults already fit.

A third optional variable, TERMINAL_SSH_PERSISTENT, controls state carry-over and gets its own step below.

Step 4: Start A Session And Check Where Commands Land

Open a fresh Hermes session so the new backend loads.

Ask the agent to run hostname and pwd through its terminal tool.

The reply should name the VPS, not the laptop.

Now type !hostname yourself in the CLI and compare.

The CLI docs say bang commands always execute where Hermes itself is installed, so this one prints the laptop's name.

That mismatch is expected and is the quickest way to confirm both sides are wired correctly.

Composer path completion goes the other way and follows the configured backend, so file paths you tab-complete come from the VPS.

🔥 Want an SSH-ready Hermes setup you can copy instead of wiring every line yourself? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS with Hermes ready to go, four coaching calls a week and 3,600+ members running agents on their own servers. → Join the AI Profit Boardroom

Step 5: Decide What State Survives Between Commands

Each agent command reaches the VPS as a new ssh … bash -c process, so state has to be carried on purpose.

Hermes handles that with terminal.persistent_shell, which ships switched on.

With it on, the current folder and anything you export survive into the next command.

Plain variables, shell functions and aliases you set mid-session are gone on the next call.

So if the agent builds a path in one step and uses it in another, tell it to export the value.

To switch carry-over off, run:

hermes config set terminal.persistent_shell false

On SSH the env variable TERMINAL_SSH_PERSISTENT overrides that key, and the key itself can also be set as TERMINAL_PERSISTENT_SHELL.

The persistent shell section notes that container and cloud backends ignore both switches.

Step 6: Forward Only The Variables A Skill Needs

Some skills need their own variables on the server, such as an API URL for a CMS.

Hermes ships those over OpenSSH SendEnv when a skill lists them in required_environment_variables or when you add them to terminal.env_passthrough.

The values travel in the client environment and never show up in the command string.

On the VPS, add a matching line to /etc/ssh/sshd_config and reload sshd:

AcceptEnv STUDIO_CMS_URL STUDIO_CMS_*

Skip that line and the server discards the values without a warning, so the remote shell just sees them as empty.

Your model provider keys, such as OPENAI_API_KEY, are never passed along, even if you list them.

How The Connection Behaves Once It's Up

At startup Hermes dials the host with StrictHostKeyChecking=accept-new, so a brand-new host key is stored on first contact.

It then keeps a ControlMaster socket open, reusing one connection and holding it for five idle minutes.

Before the first real command, it records the remote login shell's environment into a snapshot file.

Every later command loads that snapshot, changes into the tracked folder and then runs.

In practice, the agent sees the VPS's normal PATH every time without paying for a full login on each call.

Sudo On The Remote Box

If the studio's agent needs to restart nginx, it will hit sudo.

Passwordless sudo needs nothing extra.

Otherwise SUDO_PASSWORD can go in the profile's env file on the agent machine.

The tools reference says that value goes to whichever backend runs the command, so on SSH it must be the VPS password, not the laptop one.

Never type a password into a chat platform for the agent.

📞 Not sure which jobs should run on the server and which stay local? Book a free SEO strategy session with my team and map out the setup for your own machines. → Book your free strategy session

Where SSH Sits Next To Docker, Modal And Local

BackendRuns onDangerous-command checkCheckpoints
localThe Hermes machine itselfKeptTaken
sshA remote server you look afterKeptTaken
dockerOne long-lived container per Hermes processSkippedNot taken
modalA cloud sandbox VMSkippedNot taken

The check column comes from the security comparison table, which explains that container backends drop the check because the container is the boundary.

The checkpoint column comes from the checkpoints page: with docker, modal, daytona or vercel_sandbox, no checkpoints are recorded and /rollback declines to restore.

For the studio, that settles it: SSH keeps the safety prompt and the undo button while working on the live VPS.

Desktop SSH Is A Different Tool For A Different Job

People mix these two up constantly, so here is the line.

terminal.backend ssh sends one agent's commands to a server.

A Desktop SSH connection drives an entire Hermes install that lives on the server.

You add it under Settings → Gateways → Add connection, choose the SSH kind and type the host as user@host:22, with user and port optional.

The multi-connection Desktop docs say the app uses your SSH key, opens the tunnel, starts the dashboard and adopts a token over it.

A Desktop-owned remote backend shuts itself down after dashboard.ssh_isolated_idle_grace_s, 900 seconds by default, once no client is attached and no turn is running.

The v0.23.0 release keeps every registered gateway connected, so jumping to an SSH gateway is instant, and "New terminal on…" opens a shell on any of them.

That release also lets Desktop reach Windows SSH hosts.

If you plan to run several machines this way, the multi-gateway connections walkthrough covers the Desktop side in depth.

A First Real Job For The Studio's VPS

Once the hostname check passes, give the agent one small, reversible task before anything bigger.

A good first brief for the studio: list the sites under the web root, report free disk space, and show the last 50 lines of the nginx error log.

Nothing in that brief changes the server, so you can read the output and judge whether the agent is looking in the right places.

Next, try one change you can undo, such as editing a test config file in a scratch folder.

Because SSH keeps checkpoints, you can confirm that /rollback restores the file before you trust the agent with live configs.

Only after both tests pass would I hand it recurring work, like weekly log summaries or plugin update checks for the client sites.

Keep a written list of what the agent is allowed to touch on that box, and paste it into every brief.

Gotchas I'd Check On Day One

  • Password prompts. BatchMode means a password-only server simply fails to connect.
  • Missing skill variables. Check AcceptEnv on the server before blaming the skill.
  • Lost aliases. Mid-session aliases and functions vanish; export values or put them in the remote profile.
  • Bang commands. ! runs on the laptop, so don't use it to inspect the VPS.
  • Stale Desktop backends after an update. The update guide says to reconnect Desktop for an SSH backend, because restarting gateways alone won't refresh those processes.

For the maximum separation the security docs describe, run the gateway on its own machine or VM as well.

The AI Profit Boardroom has members comparing exactly these server layouts on the weekly calls.

My Verdict On Running Hermes Agent SSH Day To Day

For anyone whose real work lives on a server, the SSH backend is the setting I'd reach for first.

It keeps the dangerous-command check and checkpoints, which the container backends give up.

The setup is short, and the six steps above cover every documented knob.

The trade-off is responsibility: the server is yours, so back it up and give the login user only the access the agent needs.

If you want help choosing which jobs go to which machine, book a free SEO strategy session and bring your server list.

Also On Our Network

FAQ: Hermes Agent SSH

What are the exact steps to run Hermes Agent commands over SSH?

Run hermes config set terminal.backend ssh, add TERMINAL_SSH_HOST and TERMINAL_SSH_USER to ~/.hermes/.env, then open a new session and ask the agent to run hostname.

Which private key does the Hermes SSH backend pick?

Whatever path TERMINAL_SSH_KEY points to. Leave it unset and Hermes falls back to your system default key; TERMINAL_SSH_PORT falls back to 22.

Why did my alias stop working on the next command?

Each command is a fresh process. The persistent shell carries the working folder and exported variables, but not aliases, functions or plain variables.

Is the SSH backend safer than Docker for a live server?

They protect in different ways. SSH keeps the dangerous-command check and checkpoints on a machine you manage; Docker skips the check because the container itself is the boundary.

Can Hermes Desktop drive a Hermes install on my server?

Yes. Add an SSH connection under Settings, Gateways in user@host:22 form; the app opens the tunnel and starts the remote dashboard for you.

My skill's variables are empty on the server. What fixes it?

Add an AcceptEnv line for those variable names in the server's sshd_config and reload sshd. Without it, the server drops them silently.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

  • I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
  • I've grown a YouTube channel to 400,000+ subscribers.
  • I wrote "Link Building Mastery".
  • My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Prove key login, flip the backend, fill the env file, check hostname, and if you want the rest of the stack pre-built, join the AI Profit Boardroom or book a free SEO strategy session about your hermes agent ssh setup.

§ Field reports

Real wins from inside the AI Profit Boardroom

See all 3,400+ members →
AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot

Scroll sideways →

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts