/atn:ssh-gateway: how your agent works on SSH hosts

/atn:ssh-gateway is the skill of the standard Athenode plugin that sets how your AI agent works on your SSH hosts through the SSH gateway. Your AI tool loads it when a task needs a command, a file or the documentation of a host, and you can also run it yourself at the start of such a session.

A skill is a reusable set of instructions that an AI tool loads when it is relevant, usually run as a slash command such as /atn:mindmap. 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. A connection is one SSH host in the SSH gateway, with its login, its host key and its rules.

Run /atn:ssh-gateway

/atn:ssh-gateway

The skill takes no arguments and no flags. Your agent follows it for the rest of the task.

The skill works with the gateway tools of the Athenode MCP server, so the server must give your AI tool the gateway module, which athenode init offers when it asks "Which modules should the Athenode MCP server give your AI tools?". Connections are created in the web UI, and each one needs a trusted host key before the agent can use it. On Athenode Pro, what the agent may do follows your role in the connection's project.

What /atn:ssh-gateway does

With the skill loaded, a task on a host goes like this:

1. The agent finds the connection and reads its description and its services, with their health. It treats them as the account of what runs on the host.
2. It labels the session with the task, so that the session is easy to find in Live and History.
3. It runs the commands, background jobs and file operations the task needs, each with a reason. Each of these actions waits for your approval in Live unless a rule or the connection's confirmation mode lets it run.
4. If the host differs from its description, the agent tells you, and it updates the description and the services.
5. If the task added, changed or removed something on the host, it updates the description, the services and their health checks in the same task.
6. It reports what it ran where.

How the agent reaches a host

The agent reaches your hosts through the gateway tools only. It does not run ssh, scp, rsync or sftp from a shell, also when the gateway fails. When a connection's status is anything other than OK, such as Unreachable, Auth failed or Host key unknown, or the gateway cannot be reached, the agent stops and tells you.

What the agent records with each action

What	How the agent handles it
Reason	Every action carries a precise reason, which appears with the action in Live and History and in the audit.
Session label	The agent names the task once per session, as its session label.
Secrets	Secret values go in the command's environment variables, whose values are not recorded. The agent never writes a secret into a command, the chat, a description or a service, and never prints a secret file. It records only paths and variable names.

How the agent runs commands

• Each command runs on its own, through a POSIX shell on the host. The agent sets the working directory and environment variables per command and writes portable sh.
• Commands run without a terminal and without input, so the agent avoids anything interactive: editors, pagers, prompts and attaching to screen or tmux.
• The agent sets a timeout on anything that could hang. On a timeout the command is stopped and its partial output returns.
• It checks the exit code as well as the output, and filters output on the host to keep results small. Output above the gateway's limit is cut, and the agent reads the rest page by page only when it needs it.
• It runs a command as root with sudo only when a sudo password is stored for the connection.
• When a connection drops in the middle of a command, the agent checks whether the command took effect before it repeats one that changes state.
• Work that may take more than about a minute, such as a backup, an image pull, a build or a migration, runs as a background job. The agent follows its status and reads the end of its log.

The output limits, sudo, the file tools and background jobs are described on Commands, files and jobs.

How the agent moves files

The agent lists directories and reads small files with the file tools. For large or binary files it uses upload and download: each returns a one-time URL with a curl command, which the agent runs on its own machine with its own file path, keeping the secret header to itself. After an upload, it compares the checksum the host received with its own file's. The file never passes through the conversation. File transfers with upload and download describes the URLs, their limits and the errors.

When a host's files are managed elsewhere, such as by configuration management, a git repository or a deploy pipeline, the agent changes them there. A direct edit on the host is for emergencies, and the agent mirrors it back to the source.

How the agent keeps a host's documentation current

Each connection carries its own documentation, which you see on the connection's page and which every agent reads first.

Part	What the agent writes there
The description	What the host is (provider, operating system, addresses, role, production or not), then host-wide facts: networks and access, firewall, SSH, how deploys happen, storage and pitfalls. Up to 4,000 characters, written as a whole each time.
A service	Something that runs: a container or one product's group of containers, a daemon, a timer or cron job, a firewall or rules loader. Its name has up to 100 characters. Its description, up to 1,000 characters, says what it is, its image or binary, ports and domains, configuration and data paths, how to deploy or reload it and its pitfalls. A service that does not fit is split in two.

The documentation describes the current state only, with no history, dates, resource snapshots or secrets. Projects, rules and procedures go into the description or into the service they belong to.

Health checks the agent adds

The agent adds a health check to a service only when you ask for one. A check is a read-only command that prints one short line per thing it checks, so that a failed run explains itself. Before saving a check, the agent runs its command once as it is and once against a wrong name, to see that it fails, and after saving it runs the check once. When a service is renamed, moved or removed, its check changes with it. Intervals, timeouts and thresholds are on Services and health checks.

Changes to SSH and firewall access

When a task changes the SSH or firewall settings of a host, the agent first allows the new access, checks it with a fresh command and only then removes the old access, so that it does not lock itself out.

Questions /atn:ssh-gateway asks

The skill asks no questions of its own. The agent stops and tells you when a connection's status is not OK or the gateway cannot be reached, and it tells you when a host contradicts its documentation before it brings the documentation up to date.

Each action the agent starts may also wait for your decision in Live, where you choose Approve, Reject or Always allow…. Approvals and rules describes the approvals.

What /atn:ssh-gateway changes

Where	What changes
The host	What the task asks for, through approved gateway actions only.
History	One entry per action, with its reason and session label. Secret values passed as environment variables are not recorded.
The connection's description	Rewritten when the host changed or the description was out of date.
Services and health checks	Added, changed or removed to match the host. Creating or changing a health check needs approval, like a command.
The agent's own machine	The files the agent downloads, at the local paths it chose.

The report

At the end of the task the agent reports:

• what it ran on which connection, with the commands that changed something;
• the results that matter for the task;
• which descriptions, services and health checks it changed.