> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gatetrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an SSH server

> Connect a Linux server or local VM with a private key or password, verify its identity, and choose command limits.

Gatetrix Access 0.4.9 supports individual SSH commands on a saved server. Access
holds the login credential in macOS Keychain, so the agent can use the connection
without receiving the private key or password.

Commands run with the remote account's permissions. Use a dedicated account with
only the server access the task needs. Access does not restrict a command to
particular files, programs, or downstream network destinations.

## Before you start

Have the server hostname or IP, SSH username, port (usually 22), and login
credential. The server must be reachable from the Mac running Access. A local VM
uses the same SSH connection as a remote server.

Verify the server's SHA256 host-key fingerprint through the provider's console or
another trusted channel. This identifies the server, not your login key. For a
server offering an Ed25519 host key, run this in its trusted console:

```sh theme={null}
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256
```

Use a host key actually offered by the server's SSH configuration.

## Set up in the Mac app

1. In **Connectors**, select the intended agent profile. Open **Local apps** or
   **Online services**, then **Add connection → SSH server**.
2. Enter a connection name, hostname or IP, SSH username, port, and the verified
   **Server host-key fingerprint** in `SHA256:…` format.
3. Choose **Private key** or **Password** under **Authentication**. Password login
   requires the server to support SSH password authentication; interactive
   prompts and MFA are not supported.
4. Set **Timeout (seconds)** and **Output limit (KiB)**, then save the connection.
5. On its connection card, enter the credential yourself. For a key, use
   **Import private key…** or paste the complete key including BEGIN/END markers.
   Enter an encryption passphrase separately, then choose **Save key**. Missing
   line breaks can be restored for OpenSSH keys; preserve the original formatting
   for other formats. For password login, enter **SSH login password** and choose
   **Save password**.
6. Enable **Agent access** for the intended profile and review its command approval
   policy. Creating the connection alone does not grant access.
7. Ask the agent to run a harmless command such as `id`. If approval is required,
   decide in **Inbox → Approvals**; the agent should retrieve that saved result
   instead of submitting the command again.

You can also let an agent prepare the non-secret settings through
[Configuration Mode](https://docs.gatetrix.ai/access/connectors.md). Enter keys and passwords in Access,
not in chat. You can enter all server details directly in the Mac form if you
prefer.

## Limits and later changes

The default timeout is 30 seconds; the editable range is 0.1–45 seconds for the
whole call. Combined standard output and error output is limited to 256 KiB by
default, with an editable range of 1–256 KiB. The policy's **Window** setting is a
separate rate-limit interval, not the command timeout.

There is no interactive terminal, SFTP, or SSH forwarding. Stopping access or
reaching a limit does not undo changes or guarantee that remote background
processes stop. Do not automatically repeat a command after an uncertain outcome.

Connection settings are shared by every profile using the connection. Saving
settings stops its active commands. Changing the host, port, username, fingerprint,
or authentication method removes the saved credential; verify the new destination
before entering it again.

If authentication fails, check the username, selected method, and credential. A
connection timeout can mean the address, port, firewall, or SSH service is wrong.
For a host-key mismatch, independently verify the server identity before updating
the fingerprint. See [Approvals and audit](https://docs.gatetrix.ai/access/approvals.md) for policy decisions
and [Security model](https://docs.gatetrix.ai/access/security-model.md) for the permission boundary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.