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

# SSH

> Connect your servers over SSH so CloudThinker can check disk, memory, processes, services, and logs with key-based login

Connect a server over SSH so [CloudThinker](https://docs.cloudthinker.io/guide/agents/overview.md) can run shell commands on it: checking disk and memory, reading logs, and inspecting processes and services. You sign in with a private key, and CloudThinker pins the server's host key on first connect so it can detect an identity change.

## Prerequisites

* A server that accepts inbound SSH from CloudThinker on its SSH port. CloudThinker connects straight to **Host**: there's no jump host or bastion field. For a server behind a firewall or with no public address, see [Reaching private services](https://docs.cloudthinker.io/guide/connections/overview.md#reaching-private-services) for the environment option. These docs don't publish CloudThinker's egress IP list: ask your CloudThinker contact, or [contact us](https://cloudthinker.io/contact).
* A login user with shell access and public-key authentication enabled in `sshd`.
* A key pair whose public key is in that user's `~/.ssh/authorized_keys`.
* The **Admin** role in the CloudThinker workspace, which you need to add connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

## Setup

**1. Create a dedicated key pair**

Generate a key used only by CloudThinker, so you can revoke it without touching anything else:

```bash theme={null}
ssh-keygen -t ed25519 -C "cloudthinker" -f ./cloudthinker_key
```

This writes `cloudthinker_key` (private) and `cloudthinker_key.pub` (public). Existing RSA or ECDSA keys in OpenSSH or PEM format also work.

**2. Authorize the public key on the server**

```bash theme={null}
ssh-copy-id -i ./cloudthinker_key.pub ubuntu@server.example.com
```

Or append the contents of `cloudthinker_key.pub` to the user's `~/.ssh/authorized_keys` by hand.

**3. Add the connection in CloudThinker**

Open **More → Workspace settings → Connections**, select **SSH**, click **Connect**, and fill in **Host**, **User**, **Port**, and **Private key**. Add **Passphrase** only if the key has one. Click **Connect**.

CloudThinker connects, records the server's host key, and runs a test. The test usually finishes within 30 seconds and times out after 45.

**Success state:** the dialog shows **Connected** with "SSH connection verified and saved."

Each server is its own SSH connection. Repeat the last step for every server you want CloudThinker to reach. To point a prompt at one server, select its connection with `#` in the prompt box.

## Connection details

| Field | Required | Description | Example |
| - | - | - | - |
| **Host** | Yes | Hostname or IP address | `server.example.com` or `203.0.113.10` |
| **User** | Yes | Login user with shell access | `ubuntu` |
| **Port** | No | SSH port. Defaults to `22` | `22` |
| **Private key** | Yes | The full key, including the `BEGIN` and `END` lines | `-----BEGIN OPENSSH PRIVATE KEY-----` |
| **Passphrase** | No | Only for an encrypted key. Leave blank otherwise | Hidden |

## Required permissions

Commands run as the login user, with exactly that user's permissions. That user's permissions are the real boundary on what CloudThinker can do on the server.

> [!TIP]
>
> Create a non-root user for CloudThinker with read access to the logs and paths you care about, and no write access to production paths. Most health checks and log reads need nothing more.

Commands run without a terminal, so a `sudo` password prompt can't be answered. If you want CloudThinker to run a privileged command, allow just that command without a password in `/etc/sudoers.d/`:

```text theme={null}
cloudthinker ALL=(root) NOPASSWD: /usr/bin/systemctl restart nginx
```

## Agent capabilities

| Capability | What CloudThinker does | Approval |
| - | - | - |
| **System inspection** | Checks disk, memory, CPU, uptime, processes, and service status | No |
| **Log analysis** | Reads and searches application and system logs | No |
| **Diagnostics** | Investigates failures, connectivity, and configuration on the host | No |
| **Changes** | Runs a command that changes the server, such as restarting a service | Yes |

### Verify the connection

```text theme={null}
Show uptime, disk usage per filesystem, and the top 5 processes by memory on the server
```

Expect the uptime, a table of filesystems with their usage, and five processes with their memory use.

### Example prompts

```text theme={null}
Flag any filesystem above 80% full and list the largest directories on it
Summarize the last 100 lines of /var/log/app/error.log and group them by error type
Is nginx running, and when did it last restart?
```

## Write access

Read commands run without asking. A command that changes the server goes through Approvals, and CloudThinker shows the command in the request.

Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself.

Shell commands are free-form, and CloudThinker decides which ones count as changes. Treat the approval step as a second check, and rely on the login user's permissions to block what CloudThinker must never do.

## Host key verification

On the first connect, CloudThinker trusts and records the server's host key. Every later connection checks that the key still matches. CloudThinker doesn't display the fingerprint, so make sure the first connect reaches the right server.

If the key changes, the connection stops and shows **Host key changed**. This is expected after a server rebuild or a host key rotation. To accept the new key, click the shield icon (**Trust new host key**) next to the server and confirm with **Trust**.

> [!WARNING]
>
> Don't trust a new host key you didn't expect. An unexpected change can mean someone is intercepting the connection. Check the fingerprints on the server first, from a console you trust:
>
> ```bash theme={null}
> for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$f"; done
> ```

## Troubleshooting

> [accordion] Authentication failed
>
> * Check that the public key is in the login user's `~/.ssh/authorized_keys`.
> * Check that **User** is the account the key is authorized for.
> * Paste the private key in full, including the `BEGIN` and `END` lines.
> * Enter the **Passphrase** if the key has one.

> [accordion] Could not reach the host
>
> * Check **Host** and **Port**.
> * Allow inbound SSH from CloudThinker in your firewall, security group, or allowlist.
> * Confirm `sshd` is running and listening on that port.
> * A test that runs longer than 45 seconds times out with this same advice.

> [accordion] Host key changed
>
> Expected after a rebuild or key rotation: verify the fingerprint on the server, then choose **Trust new host key**. If you didn't expect it, investigate before trusting.

> [accordion] The remote command exited with a non-zero code
>
> SSH worked, but the command failed on the server. Check the command, the path, and whether the login user has permission to run it.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Use a dedicated key.** A key used only by CloudThinker can be removed from `authorized_keys` without affecting anyone else.
- **Rotate the key.** Generate a new key pair and add the new public key to `authorized_keys`. Open **More → Workspace settings → Connections**, select **SSH**, click the pencil icon (**Edit**) next to the server, paste the new **Private key**, and click **Save**. Run the verify prompt, and once it works, remove the old public key from the server.
- **Confirm before re-trusting.** Treat every host key change as suspicious until you've checked the fingerprint.

## Related

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Control how CloudThinker asks before it changes a server.

> [card] [Kubernetes connection](https://docs.cloudthinker.io/guide/connections/kubernetes.md)
>
> Connect clusters to inspect workloads.


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