Athenode

The SSH gateway

The SSH gateway is the part of Athenode through which your AI agent runs commands and transfers files on your SSH hosts, each action approved by you or by a rule you set. It is part of the athenode daemon and of Athenode Pro, and it is also published on its own as the ssh-gateway package.

What the SSH gateway is for

The SSH gateway gives your AI coding agent access to the servers you choose, and to nothing else. Through the SSH gateway tools of the Athenode MCP server, the agent can run a shell command, read and write files, copy files to and from a server, start a long command as a background job and watch the services that run on a host with health checks. In the web shop, the connection "staging" lets your agent read the logs of the staging server, restart its service after a deployment and check that the shop answers again.

Each action the agent asks for is shown to you before it runs, unless an allow rule of the connection or the connection's confirmation mode lets it run on its own. Some actions, such as recursive deletes and shutdowns, always wait for you. Approvals and rules describes the decision and the rules. Every action is kept in the history with its command, the reason the agent gave, the decision and the output, as history and gateway settings describes.

The agent reaches only the connections of the project its MCP session works in. It cannot add a connection or change how a connection logs in. It can read the connections, describe them and their services, and copy a connection into another project. The skill /atn:ssh-gateway gives your agent the rules for working through the gateway, and /atn:server-init documents a server's purpose and services.

On the athenode daemon, the SSH gateway asks for no sign-in. The daemon listens on 127.0.0.1 only and answers requests addressed to 127.0.0.1 or localhost on its own port, or to the host of the public URL you set for AI tools in containers. Other machines cannot reach it unless you forward its port, but any program of any user on your machine can. Run the daemon on a machine whose users and programs you trust. On Athenode Pro, every person signs in and acts with their role in the project, as the gateway on Athenode Pro describes.

Where the SSH gateway is in the web UI

The SSH gateway's pages are in the sidebar group SSH Gateway of a project: Connections, Live and History. The web UI describes the sidebar and the bar that appears while an action waits for your approval.

Page What it shows
Connections The servers agents can reach, with their status, uptime, load and disk use, updated live. Switch between List and Galaxy, a 3D map of the same connections, and filter by name, host or tag. The sidebar groups the connections by tag.
A connection's page The tabs Overview (description, services, status and host key), Settings (the connection's fields, Copy to project and Delete connection), Rules (allow rules and denylist entries of this connection) and Notifications (on Athenode Pro Team and up, the connection's webhook for service alerts).
Live The actions waiting for approval or running now, across every session. Opening an action shows its session, where you decide.
A session The actions of one agent session in order, with their output, the controls Approve, Reject and Always allow… for a waiting action, and the session's Confirmation mode.
History Every action of every session, newest first, with filters and a search over command, reason and output.
Import from SSH config Hosts of your SSH configuration file to add as connections. On the athenode daemon only.

The server's Settings page holds the settings that apply to every project: Approvals and limits, the Denylist, Service alerts and Notifications. History and gateway settings describes them.

The Galaxy view needs WebGL in the browser. Where WebGL is turned off, the List view shows the same connections.

Connections

A connection is one SSH host in the SSH gateway, with its login, its host key and its rules. A connection belongs to one project, and its name is unique in that project.

Section of the form Field What it holds
General Name Up to 200 characters. Agents name the connection by it.
Tags Comma-separated words, such as dev, rc, prod, each up to 50 characters.
Description Optional Markdown, up to 4,000 characters: what the host is for. Agents read it.
Address Host The host name or IP address, up to 255 characters.
Port 1 to 65535, 22 by default.
Username The SSH user the agent acts as.
Jump host None (direct), or another connection of the project to connect through.
Authentication Authentication How the gateway logs in, with the fields of that method (see login methods).
Sudo password (optional) The password that commands run with sudo use. Without it, the agent cannot run commands as root.
Credential mode Who logs in with these credentials Personal or shared credentials per member. On Athenode Pro only, as the gateway on Athenode Pro describes. On the daemon, everyone logs in with the connection's credentials.
Behaviour Default confirmation mode Require confirmation, the default, or Auto, which runs actions without asking except those matching the denylist. Approvals and rules describes both.
Poll status periodically On by default. Turns the status checks of this connection on or off.

The services that run on a host and their health checks are kept with the connection too. You edit them on the Overview tab, as services and health checks describes.

Add a connection

On the athenode daemon you add connections to your projects. On Athenode Pro, the owners of a project and the administrators add them.

  1. In the project's Connections page, select New connection.
  2. Enter the Name, Host, Port and Username, and choose a Jump host if the host is reached through another connection.
  3. Choose the Authentication method and enter its secret.
  4. Optional: enter the Sudo password, tags and a description.
  5. Choose the Default confirmation mode.
  6. Select Create connection.
  7. Trust the host key, as trust the host key describes.

Agents use the connection once its host key is trusted. To add many hosts at once on the daemon, import them from your SSH configuration.

Login methods of a connection

Method What you give Where it is available
Password The password. It also answers the keyboard-interactive prompts of servers that ask for the password that way. The daemon and Athenode Pro
Uploaded private key The private key in OpenSSH format, pasted into Private key (OpenSSH format), and its passphrase if it has one. The daemon and Athenode Pro
Local key path The path of a key file on the machine that runs the daemon, such as ~/.ssh/id_ed25519, and an optional passphrase. The key is read from that file at every connect. The daemon only
ssh-agent Nothing. The gateway uses the ssh-agent that SSH_AUTH_SOCK names in the environment of the daemon. The daemon on Linux and macOS

The gateway checks a key when you save it and when it connects. It refuses FIDO security keys (sk-*), OpenSSH certificates and keys in PKCS#8 format. Convert a PKCS#8 key to the OpenSSH format with ssh-keygen -p -f <file> and upload it again. On Windows, a connection that uses ssh-agent fails with "ssh-agent is not supported on Windows". Use a password, an uploaded key or a key file there.

A stored password, key, passphrase or sudo password is never shown again. The field says Stored and offers Keep stored, Replace and Clear, which takes effect when you save. Secrets are encrypted with the master key.

Tags of a connection

Tags group connections, for example by stage. The sidebar lists the connections under each of their tags, a connection with several tags under each one, and those without a tag under Ungrouped. Both the sidebar and the Connections page filter by tag.

Jump hosts

A jump host is a connection that the gateway connects through to reach another host. A jump host can itself have a jump host, in a chain of up to 32 connections, and a chain that leads back to the connection is refused with "The jump hosts lead back to this connection. Choose another jump host.". The jump host must be a connection of the same project, and it must allow TCP forwarding: otherwise connecting fails with "The jump host refuses TCP forwarding (AllowTcpForwarding).".

The host key of every connection in a chain is checked as that connection's own key, so trust the keys of the jump hosts first. A connection that another connection uses as its jump host cannot be deleted until that connection uses another jump host or none.

Trust the host key of a connection

The host key is the SSH server's key, which you trust once in the web UI. Until you trust it, the gateway uses the connection for nothing: agents get the error "Unknown host key, confirm it in the UI" and the status check stops at Host key unknown.

  1. Open the connection's Overview tab and select Test connection. The gateway connects once and shows the server's fingerprint, which starts with SHA256:.
  2. Compare the fingerprint with the one the server reports, for example with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server.
  3. Select Trust this key. The panel says "Host key trusted.".

When the server later presents a different key, the gateway refuses the connection with "Host key mismatch" until you trust the new key with the same steps. A reinstalled server explains a changed key. An unexpected change can mean that someone is intercepting the connection, so check the new fingerprint before you trust it.

The status of a connection

The gateway checks each connection every 60 seconds and shows whether it can be reached, its uptime, its load average over 1, 5 and 15 minutes and the disk use of /. These checks create no approvals and no history entries. History and gateway settings says how to change the interval.

Status Meaning
OK The host answered, with its uptime, load and disk use.
Unsupported The host answered, but it is not a Linux host, so uptime and load are not shown.
Unreachable The host cannot be reached.
Auth failed The server refused the user name or the credentials.
Host key unknown The host key is not trusted yet.
Host key mismatch The server presented a key other than the trusted one.
Not checked The connection has not been checked since it was created.
Polling off Poll status periodically is off for this connection.

After Auth failed, Host key unknown or Host key mismatch, the gateway stops checking the connection until you change its settings, trust its key or a Test connection succeeds. A successful test updates the status at once.

Copy a connection to another project

Copy a connection when another project needs the same server. The copy is independent of the original.

  1. Open the connection's Settings tab and go to Copy to project.
  2. Choose the Target project.
  3. Optional: enter the Name of the copy. Without one, the copy takes the original's name, which must not be taken in the target project.
  4. Select Copy to project. The copy opens in the target project.

The copy takes the connection's settings, credentials, host key, allow rules, denylist entries, services with their health checks, and tags. It does not take the history, background jobs, status or, on Athenode Pro, the connection's webhook. If the connection has a jump host, the target project needs a connection with the same name as that jump host, which the copy uses as its jump host; otherwise the copy is refused. Copy to project appears when there is another project you can add connections to.

From your AI tool, the agent copies a connection with the tool copy_connection. On Athenode Pro the copy uses personal credentials and carries the shared credentials only for people who manage the original, as the gateway on Athenode Pro describes.

Import connections from your SSH configuration

On the athenode daemon, you can add the hosts of your SSH configuration file as connections. The import reads the file on the machine that runs the daemon, so it is not available on Athenode Pro.

  1. On the Connections page, select Import from SSH config.
  2. In Config file, keep ~/.ssh/config or enter the path of another file, and select Preview.
  3. Read the list of hosts and any Warnings, and select the hosts to import.
  4. Select the button that names the number of hosts, such as Import 3 selected.
  5. Trust the host key of each new connection on its page before agents use it.

The preview lists each concrete Host of the file and of the files it includes with Include. Blocks with wildcards, such as Host *, are applied as defaults and are not listed. The import takes Host as the name, HostName, User, Port, the first IdentityFile as a local key path and ProxyJump as the jump host chain. A host without IdentityFile uses ssh-agent. Jump hosts that a selected host needs are imported with it. Match blocks and ProxyCommand are skipped with a warning, and /etc/ssh/ssh_config is not read.

The import brings in no secrets and no tags. Importing again updates the connections that came from the same host alias and keeps their names, secrets and tags. The result says how many connections were created and how many updated.

Delete a connection

Warning

Deleting a connection removes its stored secrets, host key, rules, services with their health checks, and background jobs. This cannot be undone.

  1. Open the connection's Settings tab and go to Delete connection.
  2. Select Delete connection, then Delete to confirm.

Open SSH sessions to the connection are closed. The history keeps the actions that ran on it. A connection used as another connection's jump host cannot be deleted, and the message names the connections that use it.

Connections and projects

Connections belong to their project and stay on the server where it lives. A project that still has connections cannot be deleted, and a project archive does not carry connections, as projects describes. To use a connection in another project on the same server, copy it.

On Athenode Pro, your role in the project decides what you do with its connections: viewers read them and what ran on them, editors run actions, and owners change and delete them. Project roles has the full matrix.

Pages about the SSH gateway