스크립트
스크립트는 VMPal이 Hub에 보관하는 셸 또는 PowerShell 스크립트입니다. Mac이나 VM, 또는 VM의 새 클론에서 실행됩니다. 클론은 깨끗한 CI 러너와 같지만 내 설정과 데이터를 그대로 갖추고 있습니다. 스크립트는 Hub에서 실행하거나, AI 에이전트나 vmpal로 실행하세요.
AI 에이전트에게 요청하기
스크립트를 작성하고 실행하는 가장 쉬운 방법은 코딩 에이전트에게 요청하는 것입니다. 에이전트가 스크립트를 작성해 VMPal Hub에 저장합니다. 지정한 위치에서 스크립트를 실행하고, 실행이 실패하면 로그를 읽습니다. 이때 에이전트는 VMPal의 MCP 도구나 터미널의 vmpal script를 사용합니다.
- VMPal에서 Settings › AI Agents를 열고 Let coding agents on this Mac manage all VMs(이 Mac의 코딩 에이전트가 모든 VM을 관리하도록 허용) 설정을 켜세요.
- Add to Claude Code나 다른 에이전트의 버튼(지원하는 에이전트)을 클릭하고 에이전트를 다시 시작하세요.
- 예를 들어 이렇게 요청하세요.
- "내 Windows VM에서 이 앱을 빌드하는 VMPal 스크립트를 작성하고 지금 실행해 주세요."
- "내 테스트 스크립트를 실행하고 왜 실패했는지 알려 주세요."
- "내 빌드 스크립트가 Ubuntu VM의 새 클론에서 실행되고, 30분이 지나면 중지되도록 바꿔 주세요."
이 페이지의 나머지 부분은 스크립트의 동작 방식이 궁금할 때 참고하세요.
스크립트 만들기
VMPal은 스크립트를 Hub에 보관합니다.
- Hub를 여세요. VMPal 창의 도구 막대에서 Hub를 클릭하거나 View › Hub(⌘2)를 선택하세요.
- New Script를 클릭하세요. 이름을 정하고, 언어를 선택하고, 스크립트를 작성한 다음 Create를 클릭하세요. 새 스크립트는 사용할 수 있는 변수를 나열한 주석으로 시작합니다.
- 실행할 위치를 선택하세요. 사이드바에서 Runs On 옆의 Choose… 버튼을 클릭하세요. 또는 스크립트 메뉴를 열고(스크립트를 오른쪽 클릭하거나 ⋯ 클릭) Change Where It Runs… 항목을 선택하세요.
Hub 목록에서 스크립트를 더블 클릭하거나 Return 키를 누르면 편집하고, Delete 키를 누르면 삭제하며, 위아래로 드래그하면 순서를 바꿉니다. VMPal의 VM 목록에서 스크립트가 실행되는 VM에는 스크립트 표시가 나타납니다. 표시를 클릭하면 Hub에서 해당 스크립트를 볼 수 있습니다.
실행 위치
스크립트는 VM의 새 클론, VM 자체, 또는 Mac에서 실행할 수 있습니다. 여러 곳을 선택하면 각 위치에서 실행됩니다.
VM에서 실행하려면 에이전트 제어가 필요합니다. 그래서 VMPal은 스크립트가 실행되는 VM마다 에이전트 제어를 켭니다.
VM의 새 클론
VM을 선택하면 이 방식이 기본값입니다. 클론은 새 CI 러너처럼 쓰고 버리는 VM의 복사본입니다. 실행할 때마다 클론이 따로 만들어지고, 실행이 끝나면 VMPal이 클론을 삭제합니다.
- 가볍습니다. VMPal은 클론을 즉시 만듭니다. 가벼운 클론에는 APFS가 필요합니다. APFS가 아닌 드라이브에 있는 VM에서는 VM 자체에서 실행됩니다.
- VM이 종료되어 있어야 합니다. VM의 Shut Down을 사용하세요. 창을 닫으면 VM이 종료되지 않고 저장됩니다.
- 실행은 VM이 종료되기를 최대 30분까지 기다립니다. 그 뒤에는 VMPal이 실행을 건너뜁니다.
- 클론에는 Mac의 어떤 것도 없습니다. 공유 폴더, 포워딩된 포트, 클립보드를 받지 않습니다.
VM 자체
VM 자체에서 실행하려면 실행 위치를 선택할 때 VM 아래의 Clone a new VM each run(실행할 때마다 새 VM 복제) 선택을 해제하세요. 그러면 사이드바의 VM 아래에 Runs in the VM itself가 표시됩니다.
- VMPal은 백그라운드에서 VM을 시작하거나 재개합니다. 로그인 화면에서는 VMPal에 저장된 비밀번호로 로그인합니다. 실행이 끝나도 VM은 계속 실행 상태로 둡니다.
- VM이 일시 정지되어 있으면 재개될 때까지 실행이 기다립니다.
- 실행은 내가 설정한 VM 자체의 공유 폴더, 클립보드, 네트워크를 그대로 사용합니다.
이 Mac
스크립트는 Mac에서 내 계정으로 실행됩니다. vmpal과 AI 에이전트가 이곳에서 스크립트를 실행하게 할 수 있는지는 Scripts on this Mac 설정이 정합니다.
실행 방식
스크립트는 실행되는 곳의 셸로 실행됩니다.
| 위치 | 언어 | 실행 도구 |
|---|---|---|
| Linux VM | Shell | bash |
| macOS VM | Shell | zsh |
| 내 Mac | Shell | zsh 또는 #! 줄에 지정한 인터프리터 |
| Windows VM | PowerShell | Windows PowerShell |
- 셸 스크립트는 로그인 셸로 실행됩니다. 홈 폴더에서 시작합니다.
- 실행은 root가 아닌 사용자 계정을 사용합니다. 로그인 셸의 파일을 읽습니다. Linux에서는
~/.profile(~/.bashrc가 아님), macOS와 내 Mac에서는~/.zprofile(~/.zshrc가 아님)입니다. 따라서 도구를 모든 사용자용으로 설치하거나 이 파일에서PATH를 설정하세요. - 종료 코드가 실행의 성공 여부를 정합니다. 종료 상태가 0이면 성공이고, 그 밖의 값이면 실패입니다.
- PowerShell은 프로그램이 실패해도 계속 진행합니다. 그러니 프로그램을 실행할 때마다
$LASTEXITCODE를 확인하세요. - VMPal은 스크립트 외에는 Mac에서 아무것도 복사하지 않습니다. 코드는
git clone등으로 스크립트가 직접 가져와야 합니다.
실행하기
사이드바나 스크립트 메뉴에서 Run Now를 클릭하세요. 스크립트가 선택한 각 위치에서 실행됩니다. 아직 위치를 선택하지 않았다면 VMPal이 어디서 실행할지 묻습니다.
다른 곳에서 실행하려면 스크립트 메뉴에서 Option 키를 누른 채 Run On… 항목을 선택하세요. VMPal이 먼저 위치를 묻습니다. 그곳에서 스크립트를 실행하고, 이후에도 계속 그곳에서 실행합니다.
기록
사이드바의 History(기록)에는 각 실행이 나열됩니다. 실행의 상태, 걸린 시간, 실패하거나 대기 중인 이유를 보여 줍니다.
- Show Log는 실행의 출력을 엽니다.
- Stop은 실행을 중지합니다. 스크립트 메뉴의 Stop Runs는 모든 실행을 중지합니다.
- 항목을 더블 클릭하면 전체 내용과 함께 각 실행의 로그를 들어오는 대로 볼 수 있습니다.
로그
로그는 Mac의 ~/Library/Logs/VMPal/Hub에 있습니다. Hub에서 Help › Show Logs in Finder를 선택하면 스크립트의 로그가 열립니다.
- VMPal은 로그 하나를 16MiB 이내로 유지합니다. 이보다 긴 로그는 처음과 끝 부분만 남깁니다.
- VMPal은 스크립트마다 마지막으로 끝난 실행 50개를 로그와 함께 보관합니다.
VMPal 종료
실행이 진행 중일 때 VMPal을 종료하면 Stop Runs and Quit으로 먼저 확인을 받습니다. 그런 다음 실행을 중지하고 클론을 삭제합니다. VMPal이 종료될 때 아직 대기 중인 실행은 시작되지 않습니다. 또한 업데이트 설치를 기다리는 동안에는 아무것도 시작되지 않습니다.
스크립트 설정
스크립트의 설정을 바꾸려면 스크립트 메뉴에서 Edit Script… 항목을 선택하거나, 사이드바에서 이름 옆의 Edit… 버튼을 클릭하세요.
| 설정 | 기능 |
|---|---|
| Language(언어) | Shell, 또는 Windows VM용 PowerShell |
| Timeout(제한 시간) | 이보다 오래 걸리는 실행은 VMPal이 중지합니다. 5분에서 6시간까지 선택할 수 있으며 기본값은 1시간입니다. vmpal로는 최대 24시간까지 지정할 수 있습니다 |
| Color(색상) | Hub의 스크립트 행과, 스크립트가 실행되는 VM의 스크립트 표시에 색을 입힙니다. Mac의 색상 중 하나를 고르거나 색 없음을 선택하세요. 스크립트 메뉴의 Color와 사이드바의 이름 옆 색상 버튼으로도 바꿀 수 있습니다 |
스크립트 메뉴에서 Duplicate를 선택하면 스크립트 바로 아래에 복사본을 만듭니다. Delete Script… 항목은 스크립트와 실행 기록, 로그를 삭제합니다.
변수
각 실행에는 다음 환경 변수가 설정됩니다.
| 변수 | 값 |
|---|---|
VMPAL_SCRIPT_NAME |
스크립트의 이름 |
VMPAL_RUN_ID |
실행의 ID |
VMPAL_TARGET |
실행 위치: mac 또는 VM의 이름 |
PowerShell에서는 $env:VMPAL_SCRIPT_NAME처럼 씁니다.
제한
- 위치마다 한 번에 하나씩 실행됩니다. 스크립트는 실행되는 각 위치에서 한 번에 하나만 실행되며, 실행 하나가 더 대기할 수 있습니다. 새 실행이 들어오면 대기 중인 실행을 대신합니다.
- 클론은 동시에 두 개까지. 클론에서 하는 실행은 동시에 최대 두 개까지 진행됩니다. 스크립트가 VM의 다음 클론을 만들려면 VMPal이 이전 클론을 삭제할 때까지 기다립니다.
- macOS VM은 동시에 두 개까지. macOS는 직접 실행한 VM을 포함해 macOS VM을 동시에 최대 두 개까지만 허용합니다. 두 개가 실행 중이면 macOS VM에서의 실행은 하나가 멈출 때까지 기다립니다.
- VM 자체에서는 스크립트에 관계없이 한 번에 하나만 실행됩니다. VM 자체에서 실행하는 스크립트는 최대 32,000바이트(UTF-8 기준)입니다. 이보다 긴 스크립트의 실행은 VMPal이 건너뛰므로, 그런 스크립트는 클론에서 실행하세요.
- 시작까지 30분. VM이 종료되기를 기다리는 경우처럼 시작하기까지 30분을 기다린 실행은 VMPal이 건너뜁니다.
이 Mac에서 실행하는 스크립트
Mac에서 실행되는 스크립트는 내 계정으로 코드를 실행합니다. 그래서 vmpal이나 AI 에이전트가 Mac에서 스크립트를 실행하게 하려고 할 때 VMPal은 설정을 확인합니다. 다음과 같은 경우입니다.
- 스크립트의 실행 위치에 Mac을 추가할 때
- Mac에서 스크립트를 지금 실행할 때
- Mac에서 실행되는 스크립트의 내용을 바꿀 때
이 설정은 Settings › AI Agents › Scripts on this Mac입니다.
| 선택 | VMPal의 동작 |
|---|---|
| Allow (agents ask you) | 기본값입니다. VMPal은 묻지 않고 허용합니다. 에이전트에게는 먼저 사용자에게 물어보라고 안내하지만, VMPal은 실제로 물어봤는지 확인할 수 없습니다. 따라서 Mac의 어떤 앱이든 이 방법으로 내 계정 권한으로 코드를 실행할 수 있습니다 |
| Ask in VMPal | 스크립트의 내용과 실행 위치를 보여 주고 사용자에게 묻습니다. 스크립트 버전마다 한 번씩 묻습니다 |
| Off | VMPal이 거부합니다 |
이 설정은 VM 안의 스크립트나 Hub에서 직접 하는 작업에는 영향을 주지 않습니다.
vmpal로 사용하기
vmpal은 docker나 gh처럼 쓰는 VMPal의 명령줄 도구입니다. vmpal script 명령은 Hub와 같은 일을 합니다.
| 명령 | 기능 |
|---|---|
vmpal script create <name> --file <path> |
스크립트를 저장합니다. 실행 위치는 VM의 새 클론이면 --run-in <VM>, VM 자체면 --run-in-place <VM>, 이 Mac이면 --host로 지정합니다 |
vmpal script run <script> --wait |
지금 실행하고 실행이 끝날 때까지 기다립니다. 종료 코드로 성공 여부를 알 수 있습니다 |
vmpal script log <script> |
가장 최근 실행의 출력을 보여 줍니다 |
vmpal script runs <script> |
실행 목록을 상태, 실패 이유와 함께 나열합니다 |
vmpal script edit <script> |
내용, 설정, 실행 위치를 바꿉니다 |
vmpal script create "Build" --file build.sh --timeout 30m --run-in "Ubuntu"
vmpal script run "Build" --wait
vmpal script log "Build"
나머지 명령은 명령 목록에서 확인하세요. AI 에이전트는 vmpal_create_script, vmpal_run_script, vmpal_get_run_log 같은 VMPal의 MCP 도구로 같은 작업을 합니다. 이 도구를 쓰려면 Let coding agents on this Mac manage all VMs 설정이 켜져 있어야 합니다.