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

# 실행 환경: 내 기기와 클라우드 서버

> 세션의 두 가지 실행 방식인 내 기기에서 실행(인터페이스에는 Run on your device로 표시되며 에이전트가 내 컴퓨터를 원격으로 조작합니다)과 클라우드 서버를 설명합니다. 선택 방법, 머신과 실행 권한, 민감한 위치 확인, 실행 기록, 다시 연결, 기기 제거를 다룹니다.

각 세션은 시작할 때 실행 방식을 선택하며, 이후에는 변경할 수 없습니다.

* **내 기기에서**(인터페이스에는 **Run on your device** 로 표시): 클라우드의 에이전트가 내 컴퓨터를 원격으로 조작합니다. 파일 읽기와 쓰기, 명령 실행은 내 컴퓨터에서 로컬 환경과 파일을 사용해 이루어지며, 결과는 로컬에서 실행한 것과 같습니다. 데스크톱 앱에 로그인되어 있고 실행을 허용한 컴퓨터라면 어느 것이든 선택할 수 있습니다.
* **클라우드 서버**: 세션이 처음부터 끝까지 내 클라우드 서버(Plus에 포함된 Linux 클라우드 서버)에서 실행되며, 내 컴퓨터를 거치지 않습니다. 노트북을 닫아도 세션은 끝까지 실행됩니다.

## 적용 범위

| 형태 | 지원 | 비고 |
| - | - | - |
| 데스크톱 앱 | 지원 | 로그인하면 이 컴퓨터가 자동으로 선택 가능한 기기가 됩니다. 실행 권한 변경과 민감한 위치 확인은 이 컴퓨터 자체의 앱에서만 할 수 있습니다 |
| 웹 앱 | 일부 지원 | 새 세션에서 클라우드 서버나 어떤 기기든 사용할 수 있습니다. 머신 목록, 실행 권한, 실행 기록은 보기만 할 수 있습니다 |
| 모바일 웹 | 일부 지원 | 웹 앱과 같습니다 |

## 비교

| | 내 기기에서(Run on your device) | 클라우드 서버 |
| - | - | - |
| 작업이 실행되는 곳 | 선택한 컴퓨터 | 내 클라우드 서버(Ubuntu 24.04) |
| 사용하는 환경과 파일 | 해당 컴퓨터의 환경과 프로젝트 폴더 | 클라우드 서버의 프로젝트 사본과 [프로젝트 환경](https://docs.aihubmix.com/ko/cloud/projects/environment-setup.md) |
| 사용할 수 있는 프로젝트 | 해당 컴퓨터의 로컬 프로젝트와 프로젝트 없는 세션 | 클라우드 프로젝트와 프로젝트 없는 세션 |
| 지원 에이전트 | 현재 Claude Code만 | 전체 |
| 요구 사항 | 컴퓨터가 온라인이고 **Allow execution** 이 켜져 있음 | Plus 요금제 |
| 컴퓨터 종료 또는 오프라인 | 이번 턴이 일시 중지되며, 컴퓨터가 다시 연결되면 자동으로 계속됩니다 | 영향 없음 |

## 진입 경로

* 새 세션: 입력창 위 **Project** 옆의 실행 환경 버튼.
* 기존 세션: 상단 표시줄 제목 옆의 실행 환경 표시.
* **Settings › Workspace › Machines**, 또는 실행 환경 메뉴 하단의 **Execution log** 와 **Machines & access**.

## 새 세션의 실행 환경 선택

실행 환경 버튼을 클릭하면 **Run environment** 메뉴가 열립니다. 상단에 **Cloud server** 가 있고, 아래 **Run on your device** 그룹에 각 기기가 나열됩니다(현재 컴퓨터에는 **This device** 가 표시되고, 두 번째 줄에 접근 범위와 권한 상한이 표시됨). 하단에는 **Execution log** 와 **Machines & access** 가 있습니다.

### 기본 선택

* 로컬 프로젝트는 프로젝트가 있는 컴퓨터가 기본값이며, 그 밖의 프로젝트와 프로젝트 없는 세션은 클라우드 서버가 기본값입니다.
* 직접 선택한 값은 이 새 세션에만 적용됩니다. 선택한 기기를 사용할 수 없게 되면 선택이 클라우드 서버로 돌아갑니다.

### 옵션을 선택할 수 없을 때

| 이유 | 메뉴의 문구 |
| - | - |
| 기기가 오프라인임 | **Device offline**(로컬 프로젝트가 있는 컴퓨터가 오프라인이면 선택은 할 수 있으며 **Device offline** 이 표시됨) |
| 기기에서 **Allow execution** 이 켜져 있지 않음 | **Not allowed to run** |
| 기기가 워크스페이스에서 제거됨 | **Device removed. Choose another environment** |
| 현재 프로젝트가 이 기기에 없음 | **This project isn’t on this device** |
| 현재 에이전트가 Claude Code가 아님 | **Running on a device supports only Claude Code for now** |
| 로컬 프로젝트에서 클라우드 서버를 선택함 | **This project is only on this computer. Choose the device it’s on** |

### 기기 권한 상한

각 기기에는 **Permission limit** 를 설정할 수 있습니다. 해당 기기를 선택하면 세션 권한 메뉴에서 상한보다 높은 단계가 회색으로 비활성화됩니다(**Above this device’s permission limit**). 선택한 권한이 상한보다 높으면 자동으로 상한까지 낮아집니다. 권한 단계는 [입력창](https://docs.aihubmix.com/ko/cloud/sessions/composer.md)을 참고하세요.

## 기존 세션의 실행 환경

상단 표시줄의 세션 제목 옆 표시에는 **Cloud server** 또는 실행 기기의 이름이 나타납니다. 기기가 오프라인이면 **Device offline** 이 표시됩니다.

* 실행 머신은 세션을 만들 때 선택되며 이후에는 변경할 수 없습니다. 다른 머신을 사용하려면 새 세션을 만드세요.
* 메뉴 하단의 **Execution log** 와 **Machines & access** 는 실행 기기의 기록과 상세 정보를 엽니다.

## 기기와 머신 목록

**기기**는 데스크톱 앱에 로그인한 컴퓨터입니다. 로그인하면 워크스페이스에 자동으로 등록되며 머신 목록과 실행 환경 메뉴에 나타납니다. 웹 앱은 기기를 등록하지 않습니다.

**Settings › Workspace › Machines** 에는 워크스페이스의 모든 머신이 나열됩니다(클라우드 서버가 맨 앞). 각 행에는 이름, OS와 앱 버전, 상태(**Online**, **Offline**, **Stopped (retained)**, **Removed**)가 표시됩니다. 앱을 다시 설치한 후 남은 이름이 같은 오프라인 기록은 한 줄로 접힙니다. 더 이상 사용하지 않으면 하나를 열어 제거하세요.

행을 클릭하면 머신 상세 정보가 열립니다.

## 머신 상세 정보와 실행 권한

컴퓨터와 서버는 이름 옆의 연필 버튼으로 이름을 바꿀 수 있습니다(최대 64자).

| 그룹 | 설정 | 값(기본값) | 설명 |
| - | - | - | - |
| 실행 권한 | 실행 허용 | 켜기 / 끄기(컴퓨터는 기본적으로 꺼짐) | 켜져 있을 때만 클라우드 에이전트가 이 머신에서 실행될 수 있습니다 |
| 실행 권한 | 접근 범위 | **Project folder only**, **Selected folders**, **Entire computer**(기본값: 컴퓨터 전체) | **Selected folders** 를 선택하면 허용할 폴더를 추가합니다 |
| 실행 권한 | 민감한 위치 | **Ask each time**(기본값), **Block access**, **Allow access** | 예: SSH, 키체인, 시스템 설정 |
| 작업 권한 | 권한 상한 | **No limit**(기본값), **Approve for me**, **Ask for approval** | 세션 권한은 이 상한을 넘을 수 없습니다 |
| 작업 권한 | 보낼 수 있는 시크릿 | **All workspace secrets**(기본값), **Selected secrets only** | 이 머신에서 사용할 수 있는 워크스페이스 시크릿을 선택합니다 |
| 환경 변수 재정의 | 변수 목록 | 없음 | 이 머신에서 실행할 때 재정의되는 환경 변수. 시크릿을 평문으로 입력하지 말고 `${VAR}` 참조를 사용하세요 |
| 실행 기록 | **View execution log** | 없음 | 아래를 참고하세요 |
| 플러그인과 Skills | **Manage this device’s plugins** | 없음 | [플러그인, MCP, Skills](https://docs.aihubmix.com/ko/cloud/integrations/plugins-mcp-skills.md)를 참고하세요 |
| 기기 관리 | **Remove device** | 없음 | 아래를 참고하세요 |

* 저장한 변경 사항은 새 세션에 바로 적용됩니다.
* 클라우드 서버의 상세 정보에는 **Allow execution**(읽기 전용), 실행 기록, 플러그인 진입점만 표시됩니다. 이름을 바꾸거나 제거할 수 없습니다.

### 시스템 확인

데스크톱 앱에서 이 컴퓨터의 실행 권한을 넓히면(**Allow execution** 켜기, 접근 범위 넓히기, 민감한 위치 열기, 권한 상한 높이기 등) 확인 대화 상자에 넓어지는 항목이 나열됩니다. **Allow execution** 을 켜면 이후 이 컴퓨터에서 실행되는 모든 세션에 적용됩니다. 권한을 좁힐 때는 확인이 필요 없습니다. **Allow execution** 을 끄면 이 기기를 사용하는 세션이 일시 중지됩니다.

### 변경할 수 있는 사람

실행 권한은 **이 컴퓨터 자체의 데스크톱 앱**에서만 변경할 수 있습니다. 다른 기기나 웹 앱에서 보면 읽기 전용이며 **Execution access can only be changed on this device.** 가 표시됩니다. 클라우드 서버의 설정도 읽기 전용입니다.

## 이 컴퓨터에서 처음 실행할 때

세션이 이 컴퓨터에서 실행되도록 설정되었지만 이 컴퓨터가 아직 요구 사항을 충족하지 않으면, 이 컴퓨터의 앱에서 세션을 열 때 안내가 표시됩니다.

* **실행 허용이 아직 켜져 있지 않음**: **Open Machines & access** 를 클릭해 **Allow execution** 을 켠 다음 돌아옵니다. 명령은 내 계정의 권한으로 실행됩니다.
* **이 컴퓨터에 아직 프로젝트 폴더가 없음**: **Allow** 를 클릭하고 이 컴퓨터에서 프로젝트 폴더를 선택합니다. 이 프로젝트에 대해서는 다시 묻지 않습니다. **Don’t allow** 를 클릭하면 이 프로젝트는 이 컴퓨터에서 실행되지 않습니다. 폴더는 클라우드에 동기화되지 않습니다.

프로젝트 없는 세션은 세션 자체의 임시 폴더를 사용합니다. 해당되는 경우 대화 상자에 내 `~/.claude/CLAUDE.md` 도 Agent에 전송된다는 안내가 표시됩니다.

## 민감한 위치 확인

기기의 **Sensitive locations** 설정이 **Ask each time** 이고 에이전트가 SSH 구성 같은 위치에 접근해야 하면, 실행 기기의 앱에 먼저 이유와 접근할 경로가 담긴 **Access request** 카드가 표시됩니다.

* **Allow once**: 이번 한 번만 접근을 허용하며, 머신 권한은 바뀌지 않습니다.
* **Deny**: 접근이 허용되지 않습니다.
* 정해진 시간 안에 응답하지 않으면 거부로 처리됩니다.
* **Later** 를 클릭해 접을 수 있습니다. 그러면 사이드바의 세션에 **Needs your input** 이 표시됩니다.

## 실행 기록

실행 환경 메뉴의 **Execution log**(이 세션) 또는 머신 상세 정보의 **View log**(이 머신의 모든 세션)에서 엽니다. 이 머신에서 에이전트가 수행한 작업이 한 줄에 하나씩 대상, 결과와 함께 나열됩니다.

실행 기기 자체의 앱에서는 **Stop processes**(진행 중인 작업과 백그라운드 프로세스 종료), **Disconnect**, **Reconnect** 도 사용할 수 있습니다. 웹 앱이나 다른 기기에서는 기록을 보기만 할 수 있습니다.

## 연결 끊김과 다시 연결

세션이 컴퓨터에서 실행 중이고 그 컴퓨터의 연결이 끊기면(종료, 절전, 오프라인, 앱 종료 등):

* 턴이 일시 중지되고, 실행 기기의 앱에서 세션 끝에 **This computer disconnected. This turn is paused.** 가 연결이 끊긴 이유와 함께 표시됩니다.
* 연결이 복구되면 중단된 곳부터 자동으로 계속되며, 완료된 작업은 다시 실행되지 않습니다. **Reconnect** 를 클릭할 수도 있습니다. 실행이 허용되지 않았거나 프로젝트 폴더가 연결되지 않은 것이 이유이면 해결 방법이 안내됩니다.
* 다른 기기와 웹 앱에서는 세션 표시에 **Device offline** 이 나타납니다.

기기가 오프라인이 되어도 세션은 클라우드 서버로 자동 전환되지 않습니다.

## 기기 제거

머신 상세 정보 하단에서 **Remove device** 를 클릭하고 확인합니다. 기기의 연결이 즉시 끊기고, 이 기기를 사용하는 세션이 중단됩니다. 나중에 다시 사용하려면 해당 기기에서 다시 로그인하세요.

* 클라우드 서버는 제거할 수 없습니다.
* 현재 컴퓨터는 여기서 제거할 수 없습니다. 로그아웃하면 제거됩니다.

## 클라우드 서버 방식

**Cloud server** 를 선택하면 세션이 전부 내 클라우드 서버에서 실행되며, 프로젝트는 클라우드 서버의 사본과 [프로젝트 환경](https://docs.aihubmix.com/ko/cloud/projects/environment-setup.md)을 사용합니다. 클라우드 서버에는 Plus가 필요하며, 없으면 메뉴의 **Cloud server** 에 **Available with Plus** 가 표시됩니다. 클라우드 서버 받기, 상태, 원격 데스크톱은 [클라우드 서버](https://docs.aihubmix.com/ko/cloud/cloud-host/overview.md)를 참고하세요.

## 자주 묻는 질문

### **Run on your device** 를 사용하면 컴퓨터를 계속 켜 두어야 하나요?

네. 컴퓨터의 연결이 끊기면 턴이 일시 중지되고, 다시 연결되면 자동으로 계속됩니다. 노트북을 닫은 후에도 세션이 계속 실행되어야 하면 클라우드 서버를 선택하세요.

### 기존 세션을 내 컴퓨터에서 클라우드 서버로 옮길 수 있나요?

아니요. 실행 머신은 세션을 만들 때 정해집니다. 바꾸려면 새 세션을 만드세요.

### 웹 앱에서 내 컴퓨터의 권한을 변경할 수 없는 이유는 무엇인가요?

실행 권한은 해당 컴퓨터 자체의 데스크톱 앱에서만 변경할 수 있습니다.

### 새 기기는 어떻게 추가하나요?

해당 컴퓨터에 데스크톱 앱을 설치하고 같은 계정으로 로그인합니다. 머신 목록에 자동으로 나타납니다. 그런 다음 해당 컴퓨터의 앱에서 **Allow execution** 을 켭니다.

## 관련 문서

* [프로젝트](https://docs.aihubmix.com/ko/cloud/projects/projects.md)
* [프로젝트 환경](https://docs.aihubmix.com/ko/cloud/projects/environment-setup.md)
* [워크스페이스 설정](https://docs.aihubmix.com/ko/cloud/settings/workspace.md)
* [새 세션](https://docs.aihubmix.com/ko/cloud/sessions/new-session.md)
* [입력창](https://docs.aihubmix.com/ko/cloud/sessions/composer.md)
* [플러그인, MCP, Skills](https://docs.aihubmix.com/ko/cloud/integrations/plugins-mcp-skills.md)
* [클라우드 서버](https://docs.aihubmix.com/ko/cloud/cloud-host/overview.md)


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