CLI

LabPod은 네 가지 기능을 하나로 담은 단일 바이너리입니다:

labpod server: HTTP 서버를 시작합니다.
labpod admin <subcommand>: 부트스트랩과 긴급 복구 작업입니다.
labpod env [--all]: 이 호스트에 적용된 환경 변수 설정을 출력합니다. 환경 변수를 참조하세요.
labpod whoami, labpod servers, labpod ws, labpod template, labpod image, labpod fs, labpod token, labpod api, labpod skill: 같은 호스트에서 실행 중인 LabPod 서비스와 통신하는 클라이언트 명령어입니다. 아래 클라이언트 명령어를 참조하세요.

labpod --version    # print build SHA
labpod --help       # print usage

데이터베이스 경로 결정

SQLite를 여는 모든 명령어는 다음 순서로 데이터베이스 경로를 결정합니다:

CLI --db <path> (하위 명령어 이후에 위치)
현재 프로세스의 LABPOD_DB 환경 변수
/etc/labpod/labpod.env에서 자동 로드되는 LABPOD_DB
현재 작업 디렉터리의 labpod.db

설치된 관리자 명령어는 sudo 기반 호스트에서 sudo로 실행하세요. Rocky/RHEL처럼 보통 root 셸에서 작업하는 시스템에서는 root 셸 탭을 사용하세요:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db list-users
# or:
sudo labpod admin list-users    # auto-reads /etc/labpod/labpod.env

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db list-users
# or:
labpod admin list-users    # auto-reads /etc/labpod/labpod.env

명령어가 사용할 경로 확인:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

labpod admin db-path
sudo labpod admin db-path

# Run these as root
labpod admin db-path

`labpod server`

labpod server [--db <path>] [--port <port>] [--dev]

플래그	기본값	참고
`--db <path>`	env / `labpod.db`에서	데이터베이스 경로 재정의
`--port <port>`	`24680`	`LABPOD_PORT` 재정의
`--dev`	off	localhost CORS 활성화, 임시 JWT 시크릿

설치된 systemd 서비스는 다음을 실행합니다:

/usr/local/bin/labpod server

설정은 /etc/labpod/labpod.env에서 가져옵니다. 전체 목록은 환경 변수를 참조하세요.

클라이언트 명령어

클라이언트 명령어는 설치된 /usr/local/bin/labpod로 LabPod 호스트에서만 실행됩니다. 로그인 절차가 없으므로 sudo 없이 일반 Linux 사용자로 실행하세요. CLI는 root가 소유한 유닉스 소켓에 접속합니다. 서버는 커널에서 호출 프로세스의 Linux UID를 읽어 LabPod 계정에 매핑합니다. --server URL, 저장된 별칭, 비밀번호, 세션 파일, PAT, TLS 옵션은 전달할 수 없으며 원격 서버 URL을 지정하면 사용법 오류로 거부됩니다. 다른 호스트에서 LabPod 서버를 다루려면 브라우저나 LabPod Connect를 사용하세요.

내 계정 확인과 호스트 하드웨어

labpod whoami
labpod servers hardware

whoami는 소켓이 인증한 Linux 계정을 보여줍니다. 종료 코드가 3이면 해당 계정에 LabPod 계정이 없거나 계정 설정이 관리자의 조치를 기다리는 상태입니다. 클라이언트 쪽에서 계정을 활성화하는 명령어는 없습니다. servers hardware는 이 호스트의 NVIDIA 드라이버, 지원하는 최대 CUDA 런타임, 각 GPU의 모델·VRAM·컴퓨트 능력을 알려줍니다. GPU 워크스페이스를 만들기 전에 labpod ws capacity(현재 할당량과 남은 여유량)와 함께 확인하세요.

워크스페이스

labpod ws list
labpod ws capacity
labpod ws recommend --template tmpl-pytorch-jupyterlab --gpu-use-case medium
labpod ws create --template tmpl-pytorch-jupyterlab --name train1 --gpu-count 1
labpod ws setup --template tmpl-pytorch-jupyterlab --name train1   # 이미지 준비 + 생성까지만
labpod ws start <workspace-id>
labpod ws logs <workspace-id> --tail 200
labpod ws logs <workspace-id> --launcher jupyter --tail 200   # 런처가 남긴 로그
labpod ws edit <workspace-id> --file patch.json               # 중지된 워크스페이스만
labpod ws rename <workspace-id> --name train2
labpod ws launchers <workspace-id>
labpod ws launcher start <workspace-id> jupyter
labpod ws launcher stop <workspace-id> jupyter
labpod ws ports <workspace-id>
labpod ws port add <workspace-id> streamlit --container-port <free-slot>
labpod ws monitor <workspace-id>          # CPU/MEM/GPU/프로세스 단발성 스냅샷
labpod ws stop <workspace-id>
labpod ws delete <workspace-id> --yes

ws create는 지정한 리소스 플래그만 서버에 전달하므로 생략한 값에는 템플릿 기본값이 적용됩니다. ws recommend는 웹 작성 화면과 동일한 안전한 기본값을 서버에 물어보되 아무것도 예약하지 않습니다. ws setup은 준비와 생성을 하나로 묶은 지속형 경로입니다. 이미지가 없으면 내려받거나 빌드한 뒤 워크스페이스를 만들지만 시작하거나 앱을 실행하지는 않으므로 이어서 ws start와 ws launcher start를 실행하세요. 전체 플래그 목록은 labpod ws --help에서 확인하세요.

--launcher 없이 실행한 ws logs는 컨테이너의 원본 stdout/stderr를 보여줍니다. --launcher <name>을 주면 LabPod가 그 앱 몫으로 남긴 지속 로그를 보여줍니다. 워크스페이스 페이지의 View app logs와 같은 로그로, 크기가 제한되어 있고 워크스페이스가 중지된 동안에도 읽을 수 있습니다. 직접 실행한 프로세스나 추가 앱 포트는 이 방식으로 수집되지 않습니다.

실행 중인 내 워크스페이스에서 대화형 입력 없이 명령 하나를 실행하려면 컨테이너 명령을 -- 뒤에 씁니다:

labpod ws exec <workspace-id> -- nvidia-smi -L
labpod ws exec <workspace-id> --timeout 600 -- bash train_prep.sh

워크스페이스 실행은 소유자만 할 수 있으며 관리자도 다른 사용자의 워크스페이스에서 실행할 수 없습니다. 기본 제한 시간은 300초, 최대 제한 시간은 600초입니다. 출력은 256 KiB까지 반환합니다. 오래 걸리는 작업은 nohup이나 setsid로 분리한 뒤 ws logs나 labpod fs read로 결과를 확인하세요.

템플릿과 이미지

labpod template list
labpod template get <template-id>
labpod template dockerfile <template-id>                 # 복제/가져오기 템플릿의 Dockerfile 출력
labpod template clone tmpl-pytorch-jupyterlab --name my-copy
labpod template export tmpl-pytorch-jupyterlab --out bundle.tar
labpod template import bundle.tar --build-later

labpod image list
labpod image allowlist
labpod image status <template-id>
labpod image pull <template-id> --wait
labpod image build <template-id> --wait
labpod image builds
labpod image overview
labpod image prune --yes

템플릿 정의를 자동화하려면 template create --file <spec.json|->와 template edit <id> --file <patch.json|->를 사용하세요. -는 표준 입력에서 JSON을 읽습니다. 가져온 템플릿은 검토할 수 있도록 비활성화된 상태로 생성됩니다. Dockerfile 기반으로 복제하거나 가져온 템플릿은 build를 마친 뒤에 활성화해야 합니다. template dockerfile <id> --set --file <path>는 복제본 자신의 편집 가능한 빌드 컨텍스트에서 Dockerfile을 교체합니다(공용 템플릿의 Dockerfile은 읽기 전용이므로 먼저 복제하세요).

워크스페이스를 시작할 때 LabPod가 없는 이미지를 pull하거나 build하지는 않습니다. 레지스트리 이미지는 image pull로 준비하고 Dockerfile 기반 템플릿은 image build로 준비한 뒤 다시 시작하세요. image pull과 image build는 각자의 루트리스 Podman 저장소에서 동작합니다. LabPod에는 공유되거나 root가 소유한 이미지 캐시가 없으므로 관리자가 설정한 레지스트리와 약관 규칙 안에서 계정마다 자기 몫의 이미지를 직접 받거나 빌드합니다.

게시형 managed 레시피는 평소대로 pull합니다. 다운로드가 실패하면 사용자 본인도 같은 검증된 이미지 참조를 담은 임베드 Dockerfile을 그대로 빌드해 개인용 대체 경로로 쓸 수 있습니다. labpod image build <template-id> --wait는 이 경우에도 쓸 수 있으며 본인이 소유한 Dockerfile 템플릿에만 한정되지 않습니다. MATLAB과 MS Code Serve-Web 같은 로컬 전용 managed 레시피는 관리자가 레시피를 활성화하면 각 사용자가 labpod image build로 자신의 계정에서 직접 빌드합니다.

LabPod에는 root 또는 공유 이미지 scope와 사용자에서 root로 이미지를 승격하는 요청이 없습니다. root는 레지스트리 정책을 구성하지만 이미지 list, pull, build, delete, prune 명령은 사용할 수 없습니다. 단순성을 위해 이러한 방식은 지원하지 않습니다. 재사용할 이미지는 외부 레지스트리에 게시하세요.

파일 전송 (`labpod fs`)

로컬 Linux 계정과 서버의 파일 루트 사이에서 파일을 옮깁니다. 스크립트나 에이전트가 브라우저 파일 관리자를 거치지 않고 입력을 올리거나 결과를 받아올 때 유용합니다. 주소 형식은 <root>/<path>이며 labpod fs roots로 사용할 수 있는 루트 id를 확인합니다(work는 워크스페이스 안의 /work에 대응합니다).

labpod fs roots
labpod fs ls work/exp1
labpod fs upload dataset.tar.gz work/exp1/        # 끝에 "/"를 붙이면 로컬 파일명을 그대로 씀
labpod fs download work/exp1/results.ckpt         # --force 없이는 덮어쓰지 않음
labpod fs archive work/exp1 exp1.tar.gz           # 디렉터리를 tar.gz로
labpod fs rm work/exp1 --recursive --yes

download와 archive는 로컬 파일을 생성하므로 template export와 마찬가지로 --json을 받지 않습니다. 모든 fs 작업은 서버 쪽에서 감사 기록으로 남습니다.

개인 액세스 토큰

개인 액세스 토큰(PAT)은 다른 호스트에서 LabPod HTTP API를 호출하는 별도의 의도적인 연동에 씁니다. 호스트 로컬 CLI 자체는 PAT를 쓰거나 저장하지 않습니다. labpod token으로 발급·조회·폐기합니다:

labpod token create --name ci-runner              # 토큰을 한 번만 출력
labpod token create --name nightly --expires 30   # 만료 기간(일) 지정 (1~365, 기본 90)
labpod token list
labpod token revoke <token-id>

새 토큰의 비밀값은 발급 시 한 번만 출력되며 서버에는 저장되지 않으므로 즉시 복사하세요. labpod가 아니라 토큰을 쓰는 스크립트나 에이전트 쪽에서 사용합니다:

curl -H "Authorization: Bearer labpod_pat_..." https://lab-gpu.example.local/api/workspaces

토큰은 발급한 사용자와 권한이 같으므로 해당 사용자의 워크스페이스, 템플릿, 이미지를 다룰 수 있지만 관리자 작업은 수행할 수 없습니다. PAT로는 토큰을 발급하거나 폐기할 수 없습니다. 토큰 발급·조회·폐기는 항상 로그인한 브라우저 세션이나 호스트 로컬 소켓 자체의 인증으로만 동작합니다.

브라우저 Settings → API tokens에서 토큰을 조회하고 폐기할 수 있습니다. 이 화면은 7일 이내에 만료되는 토큰을 표시합니다. 토큰 발급은 비밀값이 한 번만 노출되고 저장되지 않으므로 CLI에서만 가능합니다.

원시 API 전달

labpod api GET /api/usage/me
labpod api PATCH /api/users/kim --body '{"display_name":"Kim"}'
labpod api POST /api/workspaces --body @create.json

labpod api <METHOD> <path>는 지원되는 /api/* 엔드포인트에 인증된 요청 하나를 보내고 원본 응답을 그대로 출력합니다. 전용 ws/template/image 명령이 없는 나머지 모든 작업을 처리하는 탈출구입니다. 확인 프롬프트가 없으므로 원시 DELETE는 즉시 삭제를 실행합니다. 스트리밍 엔드포인트(터미널, 실시간 모니터/이벤트 스트림)는 거부되므로 --wait 옵션이 있는 전용 명령과 ws monitor를 사용하세요. 이 소켓에서는 자격 증명을 새로 만들 수 없어서 POST /api/auth/login과 비밀번호 변경은 거부됩니다.

JSON 출력과 종료 코드

스크립트에서 API 응답 원문이 필요하면 클라이언트 명령어에 --json을 추가합니다:

labpod ws list --json
labpod ws create --template tmpl-pytorch-jupyterlab --json

template export, fs download, fs archive는 각각 로컬 파일을 생성하므로 예외적으로 JSON 대신 파일을 씁니다. 종료 코드는 성공 시 0, API 또는 네트워크 오류나 확인 취소 시 1, 잘못된 사용법에는 2, 현재 Linux 계정에 LabPod 계정이 없거나 계정 설정이 완료되지 않은 경우에는 3입니다.

CLI 에이전트 스킬 설치

labpod skill install은 로컬 전용 명령으로, 바이너리에 내장된 CLI 사용법 스킬을 LLM 에이전트의 스킬 디렉터리에 설치하며 서버에는 접속하지 않습니다.

labpod skill install --agent claude   # -> ${CLAUDE_CONFIG_DIR:-~/.claude}/skills
labpod skill install --agent codex    # -> ${CODEX_HOME:-~/.codex}/skills
labpod skill install --path /path/to/skills

--agent와 --path 중 정확히 하나를 지정해야 합니다. 이미 설치된 스킬이 있으면 --force를 추가하지 않는 한 덮어쓰지 않습니다.

`labpod admin`

labpod admin [--db <path>] <subcommand> [args]

하위 명령어	기능
`migrate`	보류 중인 데이터베이스 스키마 마이그레이션 적용 (멱등성)
`create-user <name>`	LabPod 계정 생성; Linux 계정이 없으면 프로비저닝
`set-password <name>`	LabPod 비밀번호 교체 (DB만, Linux 비밀번호 아님)
`revoke-tokens <name>`	사용자의 API 토큰을 모두 폐기 (긴급 복구용, 비밀번호 재설정도 같은 효과)
`list-users`	슈퍼유저 플래그와 `PROVISIONING_CLEANUP_REQUIRED` 상태와 함께 모든 사용자 출력
`db-path`	이 실행에서 결정된 데이터베이스 경로 출력
`doctor`	호스트 전제 조건 확인 및 수정 사항 보고
`tls-fingerprint`	서빙 TLS 인증서의 SHA-256 지문 출력
`update <status\|check\|apply>`	최신 LabPod 릴리스 상태 확인, 갱신, 적용
`backup --out <path>`	명시적 파일로 일회성 스냅샷
`backup [--dir <dir>] --retention <N>`	`--dir` 또는 구성된 백업 디렉터리에 타임스탬프가 있는 스냅샷을 만들고 최신 N개로 정리
`checkpoint`	서비스를 내린 상태에서 WAL을 flush하고 SQLite sidecar를 닫음 (`labpod`와 백업을 먼저 중지하세요)
`restore <path> [--yes]`	라이브 DB에 스냅샷 복사 (서비스를 먼저 중지하세요)
`rollback list [--json]`	보관된 업그레이드 이전 복구 세트 목록과 각 세트의 적용 가능 여부 출력
`rollback apply <recovery-id> --yes`	보관된 세트의 바이너리, 애플리케이션 파일, 짝이 되는 데이터베이스를 복원
`template import <path.tar> (--owner <server_userid> \| --global)`	호스트에 있는 템플릿 번들을 가져오고 검토할 수 있도록 비활성화 상태로 생성
`license show`	trial 또는 서명된 라이선스로 해석된 권한 상태 출력
`license request`	호스트 활성화 요청 코드 출력
`license verify <file>`	라이선스 파일을 설치하지 않고 검증
`license install <file>`	라이선스 파일을 검증하고 `LABPOD_LICENSE_PATH`에 설치

create-user와 set-password는 stdin에서 비밀번호를 읽습니다. 대화형으로 입력하거나 파이프로 넘길 수 있습니다.

새로 만들거나 변경하는 LabPod 비밀번호는 정규화한 뒤 검증합니다. 일반 계정은 8~~64자 Unicode 문자, root와 superuser 계정은 12~~64자를 써야 합니다. 흔한 비밀번호, 사용자명이나 labpod에서 쉽게 나오는 추측은 거부하지만 문자 종류를 섞어야 하는 규칙은 없습니다. 기존 비밀번호는 업그레이드로 무효화되지 않습니다.

아래 예시는 Ubuntu처럼 sudo로 관리 작업을 실행하는 환경을 기준으로 합니다. Rocky/RHEL처럼 이미 root 셸에 있다면 sudo를 생략하세요.

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

# Interactive
sudo labpod admin set-password alice

# Piped (automation)
printf '%s\n' 'new-password' | sudo labpod admin --db /var/lib/labpod/labpod.db set-password alice

# Run these as root
# Interactive
labpod admin set-password alice

# Piped (automation)
printf '%s\n' 'new-password' | labpod admin --db /var/lib/labpod/labpod.db set-password alice

라이선스 명령어

서명된 라이선스가 설치되어 있지 않으면 LabPod는 내장 90일 trial 권한으로 실행됩니다. 라이선스 파일은 관리자 CLI로 로컬에 설치합니다:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin license show
sudo labpod admin license request
sudo labpod admin license verify ./license.lic
sudo labpod admin license install ./license.lic

# Run these as root
labpod admin license show
labpod admin license request
labpod admin license verify ./license.lic
labpod admin license install ./license.lic

배포된 바이너리는 로컬 요청 코드 생성, 검증, 설치, 상태 표시를 처리합니다.

템플릿 가져오기 명령어

번들이 이미 LabPod 호스트에 있어서 브라우저 업로드 없이 가져오려면 이 명령어를 사용합니다:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin template import ./template.tar --global
sudo labpod admin template import ./template.tar --owner alice

# Run these as root
labpod admin template import ./template.tar --global
labpod admin template import ./template.tar --owner alice

--global은 검토 후 모든 사용자에게 보이는 관리 템플릿을 만듭니다. --owner는 해당 Linux 기반 LabPod 사용자만 볼 수 있는 private 템플릿을 만듭니다. 가져온 템플릿은 기본적으로 비활성화됩니다.

Dockerfile 번들은 이미지 빌드가 필요하므로 CLI에서는 지원하지 않습니다. 이런 번들은 Workspace templates 관리자 영역(/admin/templates)에서 가져오세요.

일반적인 흐름

신규 프로덕션 부트스트랩:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

sudo labpod admin --db /var/lib/labpod/labpod.db migrate
sudo labpod admin --db /var/lib/labpod/labpod.db set-password root
sudo systemctl enable --now labpod

# Run these as root
labpod admin --db /var/lib/labpod/labpod.db migrate
labpod admin --db /var/lib/labpod/labpod.db set-password root
systemctl enable --now labpod

실행 중인 서비스 점검:

Ubuntu / Debian Rocky / RHEL / AlmaLinux / Fedora

systemctl status labpod
journalctl -u labpod -f
curl http://127.0.0.1:24680/api/health
curl http://127.0.0.1:24680/api/version
sudo labpod admin doctor

# Run these as root
systemctl status labpod
journalctl -u labpod -f
curl http://127.0.0.1:24680/api/health
curl http://127.0.0.1:24680/api/version
labpod admin doctor

환경 변수와 런타임 설정을 참조하세요.

CLI

데이터베이스 경로 결정

labpod server

클라이언트 명령어

내 계정 확인과 호스트 하드웨어

워크스페이스

템플릿과 이미지

파일 전송 (labpod fs)

개인 액세스 토큰

원시 API 전달

JSON 출력과 종료 코드

CLI 에이전트 스킬 설치

labpod admin

라이선스 명령어

템플릿 가져오기 명령어

일반적인 흐름

`labpod server`

파일 전송 (`labpod fs`)

`labpod admin`