> ## 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.

# SSH로 접속하기

> SSH 기반 접근을 위해 aircloud ssh를 사용합니다

`aircloud ssh`는 로컬 터미널에서 실행 중인 컨테이너에 SSH로 접속할 수 있게 해줍니다.

다음과 같은 SSH 고유 워크플로우가 필요할 때 적합합니다.

* `scp`
* SSH 터널링
* `ssh -L` 기반 포트 포워딩
* VS Code Remote SSH

Web Terminal이나 `aircloud exec`와 달리, SSH 접근은 SSH 키 등록이 필요합니다.

## 언제 사용하면 좋나요?

다음과 같은 경우 `aircloud ssh`가 적합합니다.

* `scp`로 파일을 전송해야 하는 경우
* SSH 포트 포워딩이 필요한 경우
* SSH 기반 IDE 연동이 필요한 경우
* SSH 중심 운영 워크플로우가 필요한 경우

## 콘솔에서 SSH 키 등록하기

프로젝트 사이드바에서 **SSH 키** 메뉴로 이동합니다.

<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" />

키를 추가할 때는 다음을 입력합니다.

* 알아보기 쉬운 이름
* OpenSSH 공개키 전체
* 키를 주입할 엔드포인트

<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" />

키를 추가하거나 변경할 때 엔드포인트가 이미 실행 중이면, 새 키는 다음 start 또는 재배포 시점부터 적용됩니다. 이미 실행 중인 컨테이너는 기존 키 셋을 유지합니다.

<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" />

## SSH 키 컨테이너별 적용

등록한 SSH 키는 컨테이너(엔드포인트) 단위로 개별 적용할 수 있습니다.

* **특정 컨테이너에만 적용**: 키를 등록할 때 주입할 엔드포인트를 선택해 해당 컨테이너에만 키가 주입되도록 설정할 수 있습니다.
* **활성화 / 비활성화**: 키를 삭제하지 않고 비활성화 상태로 전환할 수 있습니다. 비활성화된 키는 다음 재시작 시 주입되지 않으며, 필요할 때 다시 활성화해 재적용할 수 있습니다.

<Note>
  활성화/비활성화 변경 사항은 컨테이너를 중지 후 다시 시작해야 적용됩니다.
</Note>

## 중요한 준비사항

### AirCloud 제공 템플릿

일부 AirCloud 제공 템플릿은 Jupyter 또는 코드 환경처럼 기본적으로 SSH를 지원할 수 있습니다.

## 기본 SSH 설정 흐름

### 1. 로컬에서 키 쌍 생성

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

### 2. 공개키 확인

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

### 3. 콘솔에서 공개키 등록

AirCloud 콘솔에서:

1. **Project** 로 이동
2. **SSH Keys** 열기
3. 새 키 추가
4. 키를 주입할 엔드포인트 선택

### 4. 필요 시 엔드포인트 재시작

키를 추가하거나 변경할 때 엔드포인트가 이미 실행 중이었다면, 새 환경변수 주입이 적용되도록 엔드포인트를 중지 후 다시 시작해야 할 수 있습니다.

## `aircloud ssh`로 접속하기

### 기본 접속

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

### 특정 identity file 사용

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

### 특정 replica 지정

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

### 다른 사용자로 접속

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

### 터널만 열기

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

## VS Code Remote SSH · scp 등 외부 도구와 함께 사용하기

VS Code Remote SSH, `scp`, `rsync` 같은 외부 SSH 도구를 쓰려면, 재사용 가능한 SSH config 항목을 한 번만 등록합니다.

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

이후에는 호스트 별칭으로 접속하면 됩니다.

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

나중에 항목을 제거하려면:

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

## `aircloud ssh` vs `aircloud exec`

| 항목               | `aircloud ssh` | `aircloud exec` |
| ---------------- | -------------- | --------------- |
| SSH 키 등록 필요      | 예              | 아니요             |
| `scp` 지원         | 예              | 아니요             |
| SSH 터널링 지원       | 예              | 아니요             |
| Remote SSH 도구 지원 | 예              | 아니요             |
| 접근 속도            | 조금 더 느림        | 더 빠름            |