macOS에서 여러 Debian 데스크톱을 만들고 관리하는 CLI입니다. 작업마다 브라우저 로그인과 파일을 분리하고, 터미널에서는 SSH로, 브라우저에서는 데스크톱 화면으로 접속합니다.
시작하기 · 사용 안내 · 추가 프로그램 · 개발과 기여
- 컨테이너마다 독립된 Debian 환경과 브라우저 데이터를 유지합니다.
- Chromium과 터미널이 있는 데스크톱을 제공하고, 여러 SSH·VNC 연결을 동시에 사용할 수 있습니다.
- 컨테이너에 그룹 태그 하나를 붙이고 목록에서 그룹별로 정리해 볼 수 있습니다.
- 공용 데스크톱 이미지를 복제해 공통 패키지를 컨테이너마다 다시 설치하지 않습니다.
- 컨테이너를 파일 하나로 백업하고 다른 지원 Mac에 복원할 수 있습니다.
Plateau는 실행 환경을 관리합니다. 웹 자동화 도구와 업무 프로그램은 필요한 컨테이너에 직접 설치합니다.
macOS 13 이상의 Apple Silicon Mac이 필요합니다. 최신 릴리스에서 .pkg와 같은 버전의 .pkg.sha256 파일을 내려받습니다. 두 파일을 같은 디렉터리에 두고 아래 <버전>을 내려받은 버전으로 바꾸어 실행합니다.
shasum -a 256 -c "plateau-<버전>-macos-universal.pkg.sha256"
sudo installer -pkg "plateau-<버전>-macos-universal.pkg" -target /
plateau versionCreatrip 명의의 패키지 식별자는 com.creatrip.plateau.cli입니다. 실행 파일은 /usr/local/bin/plateau, 라이선스와 제3자 고지는 /usr/local/share/plateau에 설치합니다. 서명되지 않은 패키지는 macOS에서 별도의 설치 허용이 필요할 수 있으며, 현재 배포 절차에는 공증 단계가 없습니다. Universal 패키지에 x86_64 바이너리가 포함되어 있어도 운영 명령은 Apple Silicon의 arm64만 지원합니다.
컨테이너를 만들고 데스크톱을 엽니다.
plateau create work-a
plateau ls
plateau vnc work-a첫 실행은 Lima 호스트와 공용 데스크톱 이미지를 준비하므로 다운로드와 설치에 시간이 걸립니다. 이후 컨테이너는 준비된 이미지에서 생성합니다. Homebrew, Docker, QEMU나 macOS용 Incus를 따로 설치할 필요는 없습니다.
데스크톱 하단 패널이나 오른쪽 클릭 메뉴에서 Chromium과 터미널을 실행할 수 있습니다. 기본 터미널은 Catppuccin Mocha 테마의 Xfce Terminal이며 한글 입력기와 컬러 이모지 글꼴을 제공합니다. 터미널의 링크는 같은 컨테이너의 Chromium으로, 폴더는 Thunar 파일 관리자로 엽니다. 한글 전환과 복사·붙여넣기는 접속 안내를 참고합니다. 셸만 필요하면 plateau ssh work-a로 접속합니다. 파일과 브라우저 데이터는 컨테이너를 중지했다가 다시 시작해도 유지됩니다.
소스에서 설치하기
mise를 설치한 뒤 다음 명령을 실행합니다.
git clone https://github.com/creatrip/plateau.git
cd plateau
mise install
mise run install
export PATH="$HOME/.local/bin:$PATH"실행 파일은 기본적으로 ~/.local/bin/plateau에 설치됩니다. 새 터미널에서도 사용하려면 해당 디렉터리를 셸의 PATH 설정에 추가합니다. 다른 설치 경로는 PLATEAU_INSTALL_DIR로 지정할 수 있습니다.
터미널에서 plateau --help와 각 명령의 --help로 인자·옵션을 확인할 수 있습니다.
| 명령 | 동작 |
|---|---|
plateau create <이름> |
Debian 컨테이너를 생성·준비하고 시작합니다. |
plateau ls |
컨테이너 이름, 현재 상태, 전용 디스크 사용량과 그룹을 표시합니다. |
plateau rename <현재 이름> <새 이름> |
중지된 컨테이너의 이름과 Linux 호스트명을 변경합니다. |
plateau regroup <이름> <그룹> |
컨테이너의 그룹 태그를 지정·변경합니다. --clear로 해제합니다. |
plateau ssh <이름> |
필요하면 시작한 뒤 대화형 셸에 접속합니다. |
plateau vnc <이름> |
필요하면 시작한 뒤 브라우저로 데스크톱을 엽니다. |
plateau backup <이름> |
현재 디렉터리에 .plateau 백업 파일 하나를 만듭니다. |
plateau restore <파일> |
백업의 원래 이름과 재시작 의사를 복원합니다. |
plateau stop <이름> |
컨테이너를 중지하고 자동 시작을 해제합니다. |
plateau start <이름> |
컨테이너를 시작하고 자동 시작을 설정합니다. |
plateau rm <이름> |
중지된 컨테이너를 삭제합니다. -f를 지정하면 실행 중인 컨테이너를 중지한 뒤 삭제합니다. |
plateau update |
Lima와 호스트·공용 이미지·관리 컨테이너의 패키지를 갱신합니다. |
plateau version |
CLI 빌드 버전을 표시합니다. |
plateau --help |
도움말을 표시합니다. 개별 명령에도 --help를 사용할 수 있습니다. |
이름은 1~40자의 영문 소문자·숫자·하이픈으로 구성하고, 처음과 끝은 영문 소문자 또는 숫자여야 합니다. 이름은 Incus 인스턴스 이름, Linux 호스트명, SSH 접속 대상과 백업 식별자에 동일하게 사용합니다.
최초 운영 명령은 필요한 Lima를 준비하고 plateau-host VM과 Incus를 구성합니다. 도움말과 버전 명령은 호스트를 검사하거나 시작하지 않습니다. 이후 운영 명령은 로컬 상태를 점검하고 명시적으로 확인된 누락·중지에 필요한 준비만 수행합니다. 통신 오류나 충돌하는 설정은 자동 재초기화하지 않고 오류로 보고합니다.
첫 create는 공용 데스크톱 이미지를 만들기 때문에 패키지 다운로드와 설치가 필요합니다. 이후 생성은 같은 이미지를 복제하며 컨테이너마다 공통 패키지를 다시 설치하지 않습니다. 웹사이트 로그인과 업무 프로그램 설치는 각 컨테이너에서 진행합니다.
컨테이너마다 그룹 태그 하나를 지정할 수 있습니다. 별도의 그룹 생성·삭제는 필요하지 않습니다. 한글과 내부 공백을 포함한 최대 64자를 허용하며 앞뒤 공백·제어문자·보이지 않는 서식 문자는 거절합니다. 이름 규칙과 그룹 규칙은 서로 다릅니다.
plateau create work-a --group "업무 자동화"
plateau regroup work-a 운영
plateau ls
plateau regroup work-a --clearregroup은 기존 태그를 교체하며 실행 상태·자동 시작 의사·파일을 바꾸지 않습니다. --clear에는 새 그룹 인자를 함께 전달하지 않습니다. 준비·복원 등 미완료 작업이 있으면 먼저 마무리합니다. 생성 재시도에서 --group을 생략하면 기존 값을 유지하며, 다른 그룹을 명시하면 거절합니다.
ls는 별도 옵션 없이 전체 컨테이너를 그룹·이름 순으로 정렬하고 미지정은 마지막에 둡니다. GROUP 열은 지정한 태그를 그대로 표시하고 미지정은 -로 표시합니다.
plateau stop work-a
plateau rename work-a work-b
plateau ssh work-brename은 stop으로 중지하고 자동 시작을 해제한 컨테이너에 적용합니다. 완료 후에도 중지 상태를 유지하며 새 이름으로 start, ssh, vnc를 사용할 수 있습니다. 그룹·포트·업무 파일은 유지하고 Incus 이름, /etc/hostname, /etc/hosts의 기존 이름과 SSH 호스트 키 기록을 갱신합니다. /etc/hosts의 다른 항목과 주석은 보존합니다. 외부 스크립트나 사용자 설정에 직접 적은 이름은 자동 치환하지 않습니다.
대상 이름이 이미 있거나 다른 준비 작업이 남아 있으면 거절합니다. 변경 도중 실패하면 오류 원인을 해결한 뒤 원래의 rename <현재 이름> <새 이름> 명령을 그대로 재시도합니다. 목록에는 변경 전 또는 변경 후 이름이 보일 수 있으며, 진행 중에는 시작·중지·삭제·그룹 변경·백업·컨테이너 업데이트를 먼저 수행할 수 없습니다. 성공한 같은 요청의 재실행은 마지막 변경 출처가 일치할 때만 완료로 처리합니다.
이름을 바꾸기 전에 만든 백업은 당시 이름을 유지합니다. 이름 변경 후 만든 백업에는 새 이름이 기록됩니다.
plateau ssh work-a
plateau vnc work-a데스크톱은 애플리케이션 창이 없는 상태로 시작합니다. 하단 패널이나 바탕화면 오른쪽 클릭 메뉴에서 Terminal과 Chromium을 실행할 수 있습니다. Chromium은 자동으로 열리지 않습니다. 브라우저 데이터와 컨테이너 안에서 저장한 파일은 중지·재시작 후에도 유지됩니다.
기본 터미널은 Xfce Terminal이며, Catppuccin Mocha 공식 테마와 Noto Sans Mono 12pt 글꼴을 사용합니다. 256색·True Color와 Noto Color Emoji를 지원합니다. 테마는 터미널을 시작할 때 적용되므로 이미 열린 XTerm 창은 새 터미널로 바꾸어 사용합니다.
터미널의 URL을 오른쪽 클릭하고 Open Link를 누르면 컨테이너의 Chromium에서 열립니다. 하단 패널에서 여는 Chromium과 같은 프로필을 사용하므로 로그인 상태도 같습니다. Open File Manager Here는 현재 폴더를 Thunar 파일 관리자로 열고, Open Tab과 Open Terminal은 각각 터미널 탭과 창을 엽니다. 기본 앱 연결은 처음 구성할 때 지정하며 기존 사용자 설정은 보존합니다.
한글을 직접 입력할 때는 Mac의 입력 소스를 ABC로 두고, 컨테이너 터미널에서 Shift+Space를 눌러 두벌식 한글 입력을 켭니다. 다시 누르면 영문으로 돌아갑니다. 화면 하단 입력기 표시로 상태를 확인할 수 있습니다. Mac의 한글 입력기를 켠 채 noVNC에 입력하면 조합 중인 자모가 따로 전달될 수 있습니다. Mac에서 이미 작성한 한글은 아래 Clipboard 방법으로 그대로 붙여넣을 수 있습니다.
Mac에서 복사한 텍스트는 noVNC 화면 왼쪽 탭의 Clipboard를 열어 입력 칸에 Cmd+V로 붙여넣고, 칸 바깥을 클릭해 컨테이너로 전달합니다. 이어 컨테이너 터미널에서는 Ctrl+Shift+V, Chromium 입력창에서는 Ctrl+V로 붙여넣습니다. 터미널에서 복사할 때는 글자를 드래그한 뒤 Ctrl+Shift+C를 누릅니다. 복사한 내용은 noVNC의 Clipboard 칸에서 선택해 Cmd+C로 Mac에 가져옵니다. 터미널의 Ctrl+C는 실행 취소로 유지합니다.
이전 버전의 컨테이너와 공용 이미지는 최신 CLI의 plateau update로 갱신하며, 이 명령은 화면 세션을 재시작하므로 먼저 작업을 저장합니다. 기존 기본 터미널 바로가기와 메뉴는 새 터미널로 전환하고 사용자 지정 명령은 보존합니다. 테마·글꼴은 터미널 오른쪽 클릭 메뉴의 Preferences에서 바꿀 수 있으며, 사용자 설정은 이후 업데이트에서도 유지됩니다. 기존 XTerm의 클립보드 설정과 사용자 ~/.Xresources도 유지합니다.
여러 컨테이너에 동시에 접속할 수 있습니다. 같은 컨테이너의 SSH 연결은 각각 독립된 셸이며, VNC 연결은 하나의 데스크톱 화면을 함께 보고 조작합니다. SSH는 Plateau가 관리하는 키를 사용하고 원격 셸의 종료 코드를 그대로 반환합니다. 연결 실패는 별도 오류로 표시합니다.
접속 경로는 로컬 루프백으로 제한됩니다. 다른 컴퓨터에서 LAN을 통해 접속하는 기능은 제공하지 않습니다. 새 컨테이너는 생성 완료 전에 SSH 준비를 마치며, 과거 구성의 컨테이너는 첫 SSH 접속 때 필요한 설정을 한 번 보완합니다.
컨테이너의 plateau 사용자는 비밀번호 없이 sudo를 실행할 수 있습니다. 예를 들어 컨테이너 안에서 sudo apt-get update와 sudo apt-get install -y curl git으로 업무 프로그램을 설치합니다. SSH는 공개 키 인증만 허용하며 root의 SSH 로그인은 계속 차단합니다. 이전 컨테이너에는 새 CLI의 다음 plateau ssh 또는 plateau update에서 sudo 패키지와 권한을 반영합니다.
VNC 터미널에서도 사용자 서비스의 등록·시작을 지원합니다. 프로그램이 제공하는 설치 명령을 사용하거나 systemctl --user로 관리합니다. 이전 컨테이너에서 Process org.freedesktop.systemd1 exited with status 1로 등록이 실패하면 최신 CLI의 plateau update로 화면 세션 구성을 갱신합니다. 이 명령은 열린 데스크톱 앱을 종료하므로 실행 전에 작업을 저장해야 합니다.
recipes/에서 필요한 설치·설정 스크립트를 선택합니다. 각 파일 상단에 적힌 사용 방법에 따라 컨테이너 안의 plateau 계정으로 실행하며, 시스템 패키지와 설정을 변경하는 명령에만 sudo를 사용합니다.
001-install-hermes.sh는 새 컨테이너에 한 번 실행하는 Hermes 설치 스크립트입니다. 공식 기본 구성을 설치하고 기존 Chromium과 Plateau 화면을 연결합니다. 마지막에 화면 서비스를 재시작하므로 열린 데스크톱 앱과 화면 연결이 종료될 수 있습니다. 설치 후 다시 접속해 모델·인증을 설정하고, 메신저 연결은 별도로 설정합니다. 설치 실패 시 새 컨테이너에서 다시 실행하며, 설치가 끝난 Hermes의 버전 갱신은 hermes update를 사용합니다.
plateau ls의 STATUS는 관찰한 현재 상태입니다. running은 실행 중, stopped는 중지, broken은 Incus의 오류 상태 또는 지원하지 않는 상태를 뜻합니다. 조회 실패는 별도 오류이며 중지·누락으로 표시하지 않습니다.
macOS 로그인 후 Lima 호스트가 시작되면 자동 시작 의사가 설정된 컨테이너가 다시 실행됩니다. create, start, ssh, vnc는 이 의사를 켜고, 명시적인 stop은 끕니다. 백업을 위한 일시 중지는 사용자의 재시작 의사를 바꾸지 않습니다.
새 호스트에는 32 GiB 운영체제 디스크와 별도의 1 TiB 데이터 디스크가 구성됩니다. 두 디스크는 희소 파일이며 가상 용량 전체를 Mac에 미리 예약하지 않습니다. 실제 쓰기는 Mac의 남은 공간에 제한되고 컨테이너별 용량 할당량은 없습니다.
DISK는 해당 컨테이너만 참조하는 Btrfs 블록 사용량입니다. 공용 이미지와 공유하는 블록은 제외하므로 컨테이너 안의 파일 크기 합계나 Mac 전체 사용량과 다릅니다. 용량 계산만 실패하면 상태는 표시하고 용량을 -로 표시합니다. 기존 디렉터리 저장소는 자동 이전하거나 삭제하지 않습니다.
plateau backup work-a백업은 현재 디렉터리에 work-a-YYYYMMDD-HHMMSS.plateau 형식의 파일을 만들고 실제 경로를 출력합니다. 실행 중인 컨테이너는 내보내기 동안 일시 중지하고, 백업 성공 여부와 별개로 재시작을 시도합니다. 중지된 컨테이너는 중지 상태로 유지합니다. 기존 백업 파일은 덮어쓰지 않습니다.
Lima 호스트의 빠른 zstd 압축으로 V2 .plateau 파일을 저장합니다. 기존 V1 gzip 백업도 계속 복원할 수 있습니다. 새 V2 백업은 V2를 지원하는 CLI로 복원해야 하므로 다른 Mac으로 옮길 때도 CLI를 갱신합니다. 압축 결과를 Mac의 백업 파일에 직접 저장하므로 Mac에 백업 크기의 중간 사본을 추가로 만들지 않습니다. 압축 처리량·Mac 전송 비율·파일 마무리 단계를 표시하며, 전송 비율은 압축이 끝난 뒤의 다운로드 기준입니다. 진행 상황은 표준 오류, 완료 경로는 표준 출력으로 구분합니다.
대상 컨테이너의 Debian 기본 파일, 설치한 프로그램·라이브러리·캐시, 설정과 사용자 파일을 함께 저장합니다. 프로그램을 다시 설치하지 않고 당시 환경을 복구하기 위한 전체 컨테이너 백업입니다. macOS, Lima 호스트 전체와 공유 Linux 커널은 포함하지 않으며, 컨테이너 스냅샷도 포함하지 않습니다.
백업에는 브라우저 로그인 정보와 개인 파일이 포함될 수 있습니다. 파일은 소유자만 읽고 쓸 수 있는 권한으로 저장하지만 암호화하지 않습니다. 체크섬은 손상 검사용이며 작성자의 신뢰성을 보증하는 서명이 아니므로 신뢰할 수 있는 백업만 복원합니다.
복원할 Mac에 백업을 옮긴 뒤 다음 명령의 <백업 파일>을 실제 경로로 바꿉니다.
plateau restore "<백업 파일>"완료된 같은 이름의 컨테이너가 있으면 덮어쓰지 않고 실패합니다. 이름을 바꿔 복원하는 옵션은 없습니다. 다른 Mac으로 복원할 때도 컨테이너 이름·그룹·업무 파일·재시작 의사는 유지하지만, 호스트의 SSH·VNC 포트는 새로 할당합니다. 백업 당시 실행 의사가 켜져 있었다면 복원 후 실행을 준비하고, 꺼져 있었다면 중지 상태로 둡니다.
복원은 백업 본문을 한 번 읽으며 검증과 가져오기 파일 준비를 함께 수행합니다. VM에서 빠르게 풀 수 있도록 가져오기 파일은 zstd로 압축합니다. 검증이 끝난 파일을 호스트에 직접 전달해 추가 전송 사본을 만들지 않습니다. 기존 .plateau 파일을 그대로 사용할 수 있으며 원본은 변경하지 않습니다. 실행 환경 확인, 백업 준비·저장, 복원 검증·준비, 전송·데이터 복원과 완료 단계를 표준 오류에 표시합니다. 시간이 표시된 복원 준비·데이터 복원 단계로 지연 위치를 확인할 수 있습니다.
중단된 복원은 같은 원본 파일로 재시도합니다. 내부 임시 이름을 직접 조작할 필요는 없습니다. 오류에 복원 완료 후 start로 마무리하라는 안내가 있으면 해당 이름으로 실행합니다. 원본 파일과 가져온 데이터를 임의로 삭제해서 복구하지 않습니다.
그룹 필드가 없는 과거 V1 백업은 미지정 그룹으로 복원합니다. 그룹을 기록한 새 백업은 그룹 기능을 지원하는 CLI로 복원해야 합니다.
현재 백업 형식은 Apple Silicon의 Plateau 시스템 컨테이너를 대상으로 합니다. 다른 아키텍처, 임의의 외부 Incus 인스턴스나 Incus VM과의 호환성을 보장하지 않습니다. 이미지와의 블록 공유 관계는 파일 단위 복원으로 유지되지 않아 새 이미지 복제본보다 전용 디스크 사용량이 클 수 있습니다.
plateau update는 최신 안정판 Lima를 확인하고 호스트 패키지, 공용 데스크톱 이미지와 기존 관리 컨테이너를 갱신합니다. 초안·사전 공개 Lima 릴리스는 제외합니다. 사용할 수 있는 Lima가 없는 경우에도 안정판 조회가 필요하며, 이미 준비된 환경의 일반 명령은 원격 최신 버전을 조회하지 않습니다.
컨테이너는 작업 전의 실행 상태로 복구를 시도하며 사용자의 자동 시작 의사를 유지합니다. 사용자 프로필·메뉴·패널·바로가기는 보존하고 관리 서비스와 실행기를 갱신합니다. 새 기본 디자인이 이미 수정한 사용자 설정에 자동 적용되지 않는 것은 의도된 동작입니다.
이 명령은 Plateau CLI 자체를 교체하지 않습니다. CLI를 갱신하려면 새 설치 패키지를 설치하거나 소스에서 다시 설치합니다. 의존성 업데이트에는 자동 롤백 기능이 없습니다.
| 상황 | 확인·대응 |
|---|---|
plateau를 찾을 수 없음 |
패키지 설치는 /usr/local/bin, 소스 설치는 기본 ~/.local/bin을 사용합니다. PATH와 command -v plateau를 확인합니다. |
macOS arm64 관련 오류 |
실제 지원 대상은 Apple Silicon입니다. 패키지에 Intel 바이너리가 포함되어 있어도 운영 명령 지원을 뜻하지 않습니다. |
| 서명되지 않은 설치 패키지 경고 | README의 배포 링크에서 받은 파일과 체크섬을 확인하고 macOS의 설치 허용 절차를 따릅니다. |
| 생성 도중 실패 | 같은 이름으로 create를 재시도합니다. 이미 준비가 끝난 컨테이너는 중복 생성할 수 없습니다. |
| 이름 변경 도중 실패 | 같은 변경 전·후 이름으로 rename을 재시도합니다. 표시된 새 이름으로 다시 이름 변경을 시작하지 않습니다. |
| 복원 도중 실패 | 같은 백업 파일로 restore를 재시도하고 오류가 안내하는 후속 명령을 확인합니다. |
| 컨테이너 삭제 후 SSH 자료 정리 실패 | 같은 이름으로 rm을 재시도할 수 있습니다. |
broken, 조회 오류 또는 저장소 충돌 |
오류를 기록하고 원인을 확인합니다. 오류만을 근거로 기존 데이터나 VM을 삭제하지 않습니다. |
DISK가 -로 표시됨 |
상태 조회는 성공했지만 용량 계산이 불가능한 상태입니다. 전체 조회 실패와 구별합니다. |
자동 검사는 실제 VM 부팅·화면 조작·운영 환경 전체의 동작을 보증하지 않습니다. 새 Mac 최초 설치, macOS 재부팅, 디스크 부족, 패키지 업데이트와 장시간·대량 부하는 별도의 실행 검증이 필요합니다. 오류를 보고할 때는 수행한 명령과 확인한 범위를 함께 적습니다.
재현 가능한 오류를 보고하려면 기여 안내를 참고합니다.
Lima가 하나의 Linux 호스트 VM을 운영하고, 그 안의 Incus가 여러 비특권 Debian 시스템 컨테이너를 관리합니다. 컨테이너는 파일시스템과 사용자 환경을 분리하고 호스트의 Linux 커널을 공유합니다.
macOS
└─ Lima 호스트 VM
└─ Incus
├─ work-a: Debian 데스크톱
└─ work-b: Debian 데스크톱
접속은 로컬 루프백 경로를 사용합니다. 하나의 호스트를 공유하므로 호스트 장애는 모든 컨테이너에 영향을 줍니다. 내부 상태·잠금·복원 규칙과 설계 선택의 이유는 AGENTS.md에 정리합니다.
Copyright 2026 Creatrip. Plateau의 자체 코드와 문서는 Apache License 2.0으로 배포합니다. 프로젝트 고지는 NOTICE, 제3자 구성요소의 라이선스와 저작권 고지는 THIRD_PARTY_NOTICES.txt에 있습니다.
개발은 main 브랜치 하나에서 진행합니다. 별도 작업 브랜치나 PR을 만들지 않고, 검증한 변경을 main에 직접 커밋·푸시합니다.
개발과 기여 안내에서 개발 명령·검증 기준·레시피 관리·릴리스 절차를 확인할 수 있습니다. 저장소 작업 규칙과 현재 아키텍처·설계 원칙은 AGENTS.md에 있습니다. 개발 환경을 준비한 뒤 mise run check로 테스트·정적 분석·빌드를 확인합니다.