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

# Connect with SSH

> Access running containers over SSH using aircloud ssh

`aircloud ssh` allows you to connect to a running container from your local terminal using SSH.

It is the preferred option when your workflow depends on native SSH features, such as:

* `scp`
* SSH tunneling
* Port forwarding with `ssh -L`
* VS Code Remote SSH

Unlike the Web Terminal or `aircloud exec`, SSH access requires a registered SSH public key.

## When to Use `aircloud ssh`

Use `aircloud ssh` when you need to:

* Transfer files using `scp`.
* Create SSH tunnels or port forwarding.
* Connect using SSH-based IDEs.
* Work with an SSH-centric operational workflow.

## Register an SSH Key

Open **SSH Keys** from the Project sidebar.

<img src="https://mintcdn.com/aieev-723717ca/wvjECKx2Z_KXqy1h/images/ssh_menu.png?fit=max&auto=format&n=wvjECKx2Z_KXqy1h&q=85&s=e61e1c85dacd9e2fb353905c900ea2a9" alt="Ssh Menu" width="668" height="950" data-path="images/ssh_menu.png" />

When adding a new SSH key, provide:

* A descriptive name.
* Your complete OpenSSH public key.
* The endpoint where the key should be injected.

<img src="https://mintcdn.com/aieev-723717ca/wvjECKx2Z_KXqy1h/images/ssh-open-key.png?fit=max&auto=format&n=wvjECKx2Z_KXqy1h&q=85&s=76b0ecdaf401335792795fc1440c36d8" alt="Ssh Open Key" width="2084" height="1448" data-path="images/ssh-open-key.png" />

If the endpoint is already running when a key is added or updated, the new key is applied the next time the endpoint starts or is redeployed. Existing running containers continue using their current key set.

<img src="https://mintcdn.com/aieev-723717ca/wvjECKx2Z_KXqy1h/images/image-8.png?fit=max&auto=format&n=wvjECKx2Z_KXqy1h&q=85&s=09195a7346a4fd216e24349a651b9c39" alt="Image 8" width="1100" height="680" data-path="images/image-8.png" />

## Apply SSH Keys to Specific Containers

Registered SSH keys can be managed independently for each endpoint.

* **Apply to specific endpoints** — Select which endpoint should receive the SSH key during registration.
* **Enable or Disable** — Disable a key without deleting it. Disabled keys are no longer injected after the next container restart and can be re-enabled later.

<Note>
  Changes to SSH key settings take effect only after the container has been stopped and started again.
</Note>

## Prerequisites

### AirCloud Templates

Some AirCloud-provided templates, such as Jupyter environments and code workspaces, already include SSH support.

## Basic Setup

### 1. Generate an SSH Key Pair

```bash theme={null}
ssh-keygen -t ed25519 -C "your-email@example.com"
```

### 2. View Your Public Key

```bash theme={null}
cat ~/.ssh/id_ed25519.pub
```

### 3. Register the Public Key

In the AirCloud Console:

1. Open your **Project**.
2. Navigate to **SSH Keys**.
3. Click **Add SSH Key**.
4. Select the endpoint where the key should be injected.

### 4. Restart the Endpoint (If Required)

If the endpoint was already running when the key was added or updated, stop and restart the endpoint to apply the new SSH key.

## Connect Using `aircloud ssh`

### Connect to an Endpoint

```bash theme={null}
aircloud ssh <endpoint_id>
```

### Use a Specific Identity File

```bash theme={null}
aircloud ssh <endpoint_id> -i ~/.ssh/aircloud_key
```

### Connect to a Specific Replica

```bash theme={null}
aircloud ssh <endpoint_id> -r <replica_id>
```

### Connect as a Different User

```bash theme={null}
aircloud ssh <endpoint_id> -u myuser
```

### Open a Tunnel Only

```bash theme={null}
aircloud ssh <endpoint_id> --tunnel-only
```

## Use with VS Code Remote SSH, scp, and other tools

To use external SSH tools such as VS Code Remote SSH, `scp`, or `rsync`, register a reusable SSH config entry once:

```bash theme={null}
aircloud ssh-config <endpoint_id> --install -i ~/.ssh/id_ed25519
```

Then connect by host alias:

```bash theme={null}
ssh aircloud-<endpoint_id>
scp ./file aircloud-<endpoint_id>:/workspace/
# VS Code: Remote-SSH → Connect to Host → aircloud-<endpoint_id>
```

To remove the entry later:

```bash theme={null}
aircloud ssh-config <endpoint_id> --uninstall
```

## `aircloud ssh` vs. `aircloud exec`

| Feature                       | `aircloud ssh`  | `aircloud exec` |
| ----------------------------- | --------------- | --------------- |
| Requires SSH key registration | ✅ Yes           | ❌ No            |
| Supports `scp`                | ✅ Yes           | ❌ No            |
| Supports SSH tunneling        | ✅ Yes           | ❌ No            |
| Supports Remote SSH tools     | ✅ Yes           | ❌ No            |
| Connection speed              | Slightly slower | Faster          |