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

# vesslctl workspace

> 인터랙티브 개발 Workspace를 생성하고, 관리하고, 접속하는 방법을 알아봐요.

`workspace` 명령어(별칭: `ws`)를 사용하면 VESSL Cloud에서 인터랙티브 개발 환경을 관리할 수 있어요. Workspace는 데이터를 잃지 않고 일시정지하거나 다시 시작할 수 있는 영구 컴퓨트 세션을 제공해요.

## list

현재 팀의 모든 Workspace를 조회해요.

```bash theme={null}
vesslctl workspace list
```

| 플래그     | 기본값     | 설명                                   |
| ------- | ------- | ------------------------------------ |
| `--all` | `false` | 팀의 모든 Workspace 표시(내 Workspace만이 아닌) |

## show

특정 Workspace의 상세 정보를 표시해요.

```bash theme={null}
vesslctl workspace show <slug>
```

| 인자     | 설명                 |
| ------ | ------------------ |
| `slug` | 조회할 Workspace slug |

## create

지정된 클러스터, 리소스 스펙, 컨테이너 이미지로 새 Workspace를 생성해요.

```bash theme={null}
vesslctl workspace create --name my-workspace --cluster <slug> --resource-spec <slug> --image <image>
```

| 플래그                | 약어 | 필수  | 설명                                                                        |
| ------------------ | -- | --- | ------------------------------------------------------------------------- |
| `--name`           |    | 예   | Workspace 이름                                                              |
| `--cluster`        |    | 예   | Workspace를 실행할 클러스터 슬러그                                                   |
| `--resource-spec`  |    | 예   | 리소스 스펙 슬러그(GPU 종류, 수량, CPU, 메모리)                                          |
| `--image`          |    | 아니오 | 사용할 컨테이너 이미지                                                              |
| `--object-volume`  |    | 아니오 | Object volume 마운트(`SLUG:MOUNT_PATH`, 반복 가능)                               |
| `--cluster-volume` |    | 아니오 | Cluster volume 마운트(`SLUG:MOUNT_PATH`, 반복 가능)                              |
| `--init-script`    |    | 아니오 | Workspace 시작 시 실행할 셸 스크립트                                                 |
| `--ssh-key`        |    | 아니오 | 추가할 SSH 키 slug(반복 가능). slug는 `vesslctl ssh-key list`에서 확인할 수 있어요.         |
| `--port`           |    | 아니오 | `NAME:PORT:PROTOCOL` 형식의 추가 포트(반복 가능). 프로토콜은 `http`, `tcp`, `udp` 중 하나예요. |

**예시:**

```bash theme={null}
vesslctl workspace create \
  --name my-workspace \
  --cluster <cluster-slug> \
  --resource-spec <spec-slug> \
  --image quay.io/vessl-ai/torch:2.9.1-cuda13.0.1-py3.13-slim \
  --ssh-key <ssh-key-slug> \
  --port jupyter:8888:http \
  --port api:8000:tcp
```

<Tip>
  `vesslctl cluster list`와 `vesslctl resource-spec list`로 사용 가능한 클러스터와 GPU 스펙을 확인할 수 있어요. SSH 키 slug는 `vesslctl ssh-key list`로 확인할 수 있어요.
</Tip>

<Note>
  **가격 요약과 크레딧 잔액.** `workspace create`와 `workspace start`는 실행 전에 리소스 스펙, 시간당 비용, 현재 크레딧 잔액, 예상 잔여 시간을 보여줘요. 잔액이 0 이하면 생성이 차단돼요. `vesslctl billing show`로 확인하거나 크레딧을 충전한 다음 다시 시도해 주세요.
</Note>

<Info>
  **Workspace 안에서 vesslctl 그대로 사용하기.** 모든 Workspace에는 아래 환경 변수가 미리 세팅돼 있어서, JupyterLab 터미널이나 SSH 세션에서 별도 인증 없이 `vesslctl`을 바로 사용할 수 있어요:

  * `VESSLCTL_ACCESS_TOKEN`: 워크로드 범위 토큰이에요. API 호출 시 Bearer로 사용돼요.
  * `VESSLCTL_ORG`: Workspace를 소유한 조직 이름
  * `VESSLCTL_TEAM`: Workspace를 소유한 팀 이름

  `vesslctl workspace list`, `vesslctl job create`, `vesslctl volume upload` 같은 명령을 바로 사용할 수 있어요. 워크로드 토큰에는 알아두면 좋은 두 가지 제약이 있어요:

  * **단일 팀 범위로 한정**: Workspace를 소유한 팀의 자원만 조회·수정할 수 있어요. 다른 팀 목록을 보거나 `vesslctl team switch`로 컨텍스트를 바꾸는 동작은 막혀 있어요.
  * **SSH 키 관리 불가**: SSH 키 등록과 삭제는 사용자 계정 레벨 동작이라 워크로드 토큰으로는 거부돼요. 먼저 로컬에서 [`vesslctl ssh-key add`](/ko/cli/commands/ssh-key#add)로 키를 등록한 다음, Workspace 생성 시 `vesslctl workspace create --ssh-key <ssh-key-slug>`로 추가해 주세요.
</Info>

## start

일시정지된 Workspace를 다시 시작해요.

```bash theme={null}
vesslctl workspace start <slug>
```

| 인자     | 설명                    |
| ------ | --------------------- |
| `slug` | 다시 시작할 Workspace slug |

## pause

실행 중인 Workspace를 일시정지해요. 일시정지 중에는 과금이 중단되지만, 모든 데이터는 보존돼요.

```bash theme={null}
vesslctl workspace pause <slug>
```

| 인자     | 설명                   |
| ------ | -------------------- |
| `slug` | 일시정지할 Workspace slug |

## terminate

Workspace와 관련된 모든 데이터를 영구적으로 삭제해요.

```bash theme={null}
vesslctl workspace terminate <slug>
```

| 플래그     | 약어   | 설명           |
| ------- | ---- | ------------ |
| `--yes` | `-y` | 확인 프롬프트 건너뛰기 |

**예시:**

```bash theme={null}
vesslctl workspace terminate my-workspace-abc123 --yes
```

## logs

Workspace의 로그를 확인해요.

```bash theme={null}
vesslctl workspace logs <slug>
```

| 플래그       | 약어 | 기본값   | 설명         |
| --------- | -- | ----- | ---------- |
| `--limit` |    | `100` | 반환할 로그 줄 수 |

**예시:**

```bash theme={null}
vesslctl workspace logs my-workspace-abc123 --limit 500
```

## ssh

실행 중인 Workspace에 SSH 세션을 열어요.

```bash theme={null}
vesslctl workspace ssh <slug>
```

| 플래그     | 약어   | 설명          |
| ------- | ---- | ----------- |
| `--key` | `-i` | SSH 개인 키 경로 |

**예시:**

```bash theme={null}
vesslctl workspace ssh my-workspace-abc123 -i ~/.ssh/id_rsa
```

이 명령은 로컬의 `ssh` 바이너리를 Workspace의 SSH 엔드포인트로 실행하고, 등록된 SSH 키로 인증해요. 브라우저 OAuth 단계는 없어요. 먼저 [`vesslctl ssh-key add`](/ko/cli/commands/ssh-key#add)나 콘솔의 **Settings > SSH Keys**에서 키를 등록해 주세요.

<Tip>
  **브라우저, JupyterLab, VS Code로 접속하고 싶나요?** Workspace 상세 페이지의 **Connect** 탭에는 HTTP 서비스(JupyterLab과 사용자가 연 추가 포트)가 클릭 가능한 URL로 나열되고, VS Code Remote-SSH용 SSH config 블록도 복사할 수 있어요. 전체 접속 방법은 [Workspace에 접속하기](/ko/member/workspace/connect)를 참고하세요.
</Tip>