Knowledge & tools

SSH tool

The SSH tool lets an agent run shell commands on a server you control — over an authenticated SSH connection, with the server's identity pinned so the agent only ever connects to the real host. Set it up once as a tool configuration, then assign it to a bot.

An SSH tool runs real commands on a real server. Treat it like handing out a shell account: give it a least-privilege login (a dedicated user, ideally read-only), and read Safety in autonomous runs before scheduling a bot that uses it.

Connection details

When you create the tool, you provide where to connect and who to connect as:

Host — the server's IP address or hostname.
Port — the SSH port (defaults to 22).
Username — the account the agent logs in as. The key you set up below must be authorized for this account.

Pin the server's host key

The pinned host key is the server's own public host key. Hania memorizes it so that if anything ever impersonates that address, the key won't match and the tool refuses to connect — it blocks man-in-the-middle attacks. It's required: the tool won't connect without it.

On the server, read its key (reading it locally is more trustworthy than scanning over the network):

ssh-keyscan -t ed25519 localhost

That prints a line like localhost ssh-ed25519 AAAA…. Paste only the key — from ssh-ed25519 onward, dropping the leading host:

ssh-ed25519 AAAA…

Reading from another machine? Replace localhost with the server's IP or hostname. To drop the host automatically, append | cut -d' ' -f2-. If the server has no ed25519 key, run ssh-keyscan localhost (all types) and paste one key the same way.

Authenticate with a key

Hania logs in with an SSH private key. This is a key pair you create: the public half goes onto the server, and the private half goes into the tool. Generating the key isn't tied to any account — the account only matters when you authorize the public half.

On the server, create a dedicated pair (easy to revoke later):

ssh-keygen -t ed25519 -f hania_key

Authorize the public half for the account the agent logs in as (run as that account):

mkdir -p ~/.ssh && cat hania_key.pub >> ~/.ssh/authorized_keys

Print the private half and paste it into the tool's private key field — everything, including the -----BEGIN…----- and -----END…----- lines:

cat hania_key

The key must be in OpenSSH or PEM format (it begins with -----BEGIN OPENSSH PRIVATE KEY----- or -----BEGIN … PRIVATE KEY-----). PuTTY .ppk keys aren't supported — in PuTTYgen, use Conversions → Export OpenSSH key first. If the key has a passphrase, also fill in the Key passphrase field. Like all tool secrets, the private key is write-only — Hania never shows it back.

Allow Hania through the firewall

Hania connects to your server from app.hania.ai. If the server's firewall restricts inbound SSH (a cloud security group, ufw, etc.), allow app.hania.ai on the SSH port, or the connection will time out.

Test the connection

Use Test on the saved tool to run a command and confirm everything is wired up. The SSH tool takes a single parameter — the command to run — so a quick check is:

{ "command": "whoami" }

A successful test returns the command's exit code and combined output. A non-zero exit code still counts as a successful run (the command executed); authentication, connection, or timeout problems come back as a failure with an error.

Testing really executes the command on the server — it isn't a dry connection check. Start with a harmless, read-only command.

Safety in autonomous runs

Because SSH is remote command execution, a new SSH tool is classified destructive by default. In scheduled or triggered (autonomous) runs, destructive-classified tools are blocked unless the bot explicitly allows them — interactive chat is never affected. The block is by classification, not by command, so it applies even to a read-only command.

The stronger control is the login itself: give the tool a least-privilege account — for example a read-only user, or one restricted to specific commands — and classify the tool to match what that account can actually do. A limit enforced at the server can't be bypassed by a prompt injection or a model mistake, the way an app-layer toggle could. See Safety in autonomous runs for the full picture.