Skip to content

DOCS · ADVANCED · REMOTE AI-AGENT ACCESS

Run Ether from Claude or OpenAI, over SSH

HYVE Ether OS is a full Linux-based operating system, so any AI agent that can open an SSH session — Claude Code, or an OpenAI-based agent — can log into your HYVE machine from another computer and operate it: run commands, launch programs, and edit files — and, where those surfaces are enabled, drive HYVE's own agent stack too. This guide sets that up the sovereign, security-first way.

READ THIS FIRST — THE ONE HARD RULE

Never expose SSH (port 22) to the open internet. Reach your machine across networks through a private VPN mesh (WireGuard or Tailscale) instead. And understand what you're granting: an agent with an SSH shell can do anything the login user can do on that machine. Treat handing an agent SSH exactly like handing a stranger the keyboard — because functionally, you are. Section 5 shows how to fence it in.
What you'll need: your HYVE Ether OS machine (the host), the computer the agent runs on (the controller — your laptop, a server, wherever Claude Code or your OpenAI agent lives), and about 20 minutes. On the same local network? You can skip the VPN in Section 2 and use the host's LAN IP.
01

Turn on SSH on your HYVE machine (the host)

On the HYVE Ether OS machine, open a terminal and enable the OpenSSH server:

# Install the SSH server if it isn't already present, then start it
sudo apt update && sudo apt install -y openssh-server
sudo systemctl enable --now ssh

# Confirm it's listening, and find this machine's address
systemctl status ssh --no-pager
hostname -I     # your LAN IP is the 192.168.x.x or 10.x.x.x value (ignore 127.0.0.1)

Write that address down — you'll use it (or the VPN address from Section 2) in every command below. Then create the login account the agent will use. A dedicated user is cleaner than reusing your own — it lets you scope and revoke agent access independently (Section 5):

# Recommended: a dedicated, low-privilege user for the agent
sudo adduser hyve-agent

Leave this terminal open — you'll harden the SSH config in Section 3 once keys are in place.

02

Reach the host from another network — privately

To connect from a different network without opening any public port, put both machines on a private mesh. Two good options; the first is the fully-sovereign one.

A. WireGuard (self-hosted, no third party)

WireGuard is a tiny, fast VPN with no coordination server you don't control — the most sovereign choice. Install it on both machines and generate a key pair on each (the files land in your current directory):

sudo apt install -y wireguard
umask 077; wg genkey | tee privatekey | wg pubkey > publickey

Now write /etc/wireguard/wg0.conf on each machine. Each machine's PrivateKey is the contents of its own privatekey file; the [Peer] PublicKey is the other machine's publickey.

On the HOST — /etc/wireguard/wg0.conf

[Interface]
Address = 10.99.0.1/24
ListenPort = 51820
PrivateKey = <paste HOST privatekey>

[Peer]
PublicKey = <paste CONTROLLER publickey>
AllowedIPs = 10.99.0.2/32

On the CONTROLLER — /etc/wireguard/wg0.conf

[Interface]
Address = 10.99.0.2/24
PrivateKey = <paste CONTROLLER privatekey>

[Peer]
PublicKey = <paste HOST publickey>
Endpoint = <host-public-ip-or-ddns>:51820
AllowedIPs = 10.99.0.1/32
PersistentKeepalive = 25

Bring it up on both machines with sudo wg-quick up wg0. The host is then reachable at 10.99.0.1 from the controller.

WIREGUARD NEEDS ONE REACHABLE ENDPOINT

At least one peer — normally the host — must be reachable at the Endpoint above: a static or dynamic public IP, or a single forwarded UDP port (51820 is far safer to forward than SSH — it's a silent, unauthenticated-looking port with no login prompt to brute). If both machines sit behind home NATs with no forwarding at all, raw WireGuard can't link them — that is exactly the gap Tailscale (option B) closes for you.

B. Tailscale (easiest)

Tailscale wraps WireGuard with automatic key exchange and NAT traversal, so it works even when both machines are behind home routers. It relies on a coordination service you don't host, so it's less sovereign than raw WireGuard — but it's the fastest to stand up. On both machines:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# On the HOST, find its mesh address to SSH to:
tailscale ip -4        # its 100.x.y.z address
tailscale status       # lists every machine on your tailnet

IF YOU CANNOT USE A VPN AT ALL

Same local network is fine — just use the host's LAN IP. Exposing SSH across the open internet is a real, constantly-scanned attack surface — exhaust the VPN path first. A non-standard port is not a security control (it only cuts log noise). If exposure is truly unavoidable: key-only auth (Section 3), PermitRootLogin no, AllowUsers scoped to just the agent account, a low MaxAuthTries, firewall rate-limiting, fail2ban, and ideally short-TTL SSH certificates instead of a standing key. Even then, fail2ban does little against key-scanning or an sshd zero-day — a VPN avoids the whole problem.
03

Use SSH keys, then lock the door

On the controller (where the agent runs), generate a dedicated key pair — no password login, ever. Give it a passphrase when prompted:

ssh-keygen -t ed25519 -C "hyve-agent" -f ~/.ssh/hyve_ether
chmod 600 ~/.ssh/hyve_ether

# Copy the PUBLIC key to the host (replace user + address):
ssh-copy-id -i ~/.ssh/hyve_ether.pub hyve-agent@10.99.0.1

THIS PRIVATE KEY IS THE CROWN JEWEL

Anything that can read ~/.ssh/hyve_ether gets a shell on your HYVE machine — a stolen laptop, a synced folder, or a prompt-injected agent with file access. Protect it with a passphrase (load it into an ssh-agent so you type it once), keep it chmod 600, and never commit or sync it. For unattended agents, prefer a hardware-backed key (a security key) or short-lived SSH certificates over a bare passwordless key.
Controller on macOS? The commands above are identical. On Windows? Use the built-in OpenSSH client — the key path is %USERPROFILE%\.ssh\hyve_ether. Since ssh-copy-id isn't included on Windows, append the key by hand in PowerShell:
type $env:USERPROFILE\.ssh\hyve_ether.pub | ssh hyve-agent@10.99.0.1 "cat >> ~/.ssh/authorized_keys"

Confirm key login works, then turn passwords off. On the host, edit the SSH config:

sudo nano /etc/ssh/sshd_config

# Set (or add) these lines:
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
AllowUsers hyve-agent youradmin   # include EVERY account you still need to reach

# Save, then apply:
sudo systemctl restart ssh

DON'T LOCK YOURSELF OUT

Before you run systemctl restart ssh: keep your current terminal open, and in a second window confirm a fresh key login works — ssh -i ~/.ssh/hyve_ether hyve-agent@10.99.0.1. Once passwords are off, anyone not in AllowUsers and without a key is locked out — so list your own admin account there too.

If a firewall is on, allow SSH only from your private network — never from everywhere:

# Example: allow SSH only from the WireGuard subnet
sudo ufw allow from 10.99.0.0/24 to any port 22 proto tcp

From the controller, you now connect with:

ssh -i ~/.ssh/hyve_ether hyve-agent@10.99.0.1
04

Point the agent at the host

With SSH working, there are two clean ways to let Claude Code or an OpenAI agent operate the machine.

Pattern A — Run the agent ON the host (simplest, full power)

SSH in from the controller, then run your agent right there on HYVE Ether OS. It operates the machine locally with the login user's permissions:

ssh -i ~/.ssh/hyve_ether hyve-agent@10.99.0.1

# ...now on the HYVE machine, launch your agent, e.g.:
claude          # Claude Code
# or an OpenAI-based CLI agent you've installed (aider, etc.)
This is the most direct path and matches HYVE's design: the OS is agent-native, so an agent running on it can reach HYVE's own surfaces — the Omega agent, the studios, and the local models, where those services are running — the same way you would.

Pattern B — Drive the host FROM an agent on the controller

Keep the agent on your controller and give it a tool that runs a command on the host over SSH. Any agent that can call a shell command can use this — Claude Code, or an OpenAI function-calling agent:

# A "run on HYVE" tool the agent calls with a command string:
ssh -i ~/.ssh/hyve_ether hyve-agent@10.99.0.1 "<command>"

# e.g. the agent asks the OS what's running:
ssh -i ~/.ssh/hyve_ether hyve-agent@10.99.0.1 "uptime; systemctl status --no-pager"

For Claude Code, expose that as a small MCP tool or a permitted Bash command; for an OpenAI agent, register it as a function whose argument is the command to run.

A RAW COMMAND TOOL IS ARBITRARY-CODE EXECUTION

Handing an LLM a tool that runs any command string on your machine is the single highest-risk setup: anything the agent reads — a web page, a file, an email — could carry a prompt injection that makes it run destructive or data-exfiltrating commands. Where you can, pin the agent's key to a forced-command wrapper that allow-lists a fixed set of operations (Section 5) instead of a raw pass-through — and always run it as the least-privileged hyve-agent user with no sudo.

Optional — HYVE's native agent surfaces

HYVE Ether OS ships an MCP bridge that MCP-compatible agent tools can connect to, and it can act as an OpenAI-compatible model provider on your network. If you've enabled those in the OS's settings, you can also point an agent at HYVE's own AI over the same private VPN — no cloud, running on the hardware you own. Enable them from inside the OS first; the plain SSH paths above always work regardless.

05

Fence in what the agent can do

An SSH shell is total access. Scope it to your comfort level — especially if you don't fully trust every action the agent might take:

  • Dedicated user, least privilege. Use the hyve-agent account, not your own. Grant it only the sudo rights it truly needs — ideally none.
  • Constrain the key — all three, together. In ~/.ssh/authorized_keys, prefix the agent's key with from="10.99.0.0/24" (source-IP fence), restrict (disables port-, agent-, and X11-forwarding and PTY — future-safe), and command="/usr/local/bin/agent-wrapper" (a script that runs only an allow-listed set of operations). They're orthogonal — one alone is not a jail. The client's requested command arrives in $SSH_ORIGINAL_COMMAND; your wrapper must validate or ignore it — never blindly eval it. Example line:
    from="10.99.0.0/24",restrict,command="/usr/local/bin/agent-wrapper" ssh-ed25519 AAAA... hyve-agent
  • Watch it. SSH auth events are in the system journal — journalctl -t sshd (or journalctl -u ssh) — and, where you've enabled it, HYVE's own audit ledger gives every action a tamper-evident trail.
  • Kill it fast. To revoke access instantly: delete the agent's line from authorized_keys, or sudo systemctl stop ssh, or drop the VPN.

THE SOVEREIGN POINT

Everything here runs on hardware you own, over a network you control, with no cloud in the path. The agent can be Claude or OpenAI in the driver's seat — but the machine, the data, and the off-switch stay entirely yours.
INSTALL INSTRUCTIONS← BACK TO DOCS