CLI

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

labpod server: HTTP 서버를 시작합니다.
labpod admin <subcommand>: 부트스트랩 및 긴급 복구 작업.
labpod login, labpod ws, labpod template, labpod image, labpod token: 실행 중인 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에서 가져옵니다. 전체 목록은 환경 변수를 참조하세요.

로그인 사용자 명령어

워크스테이션이나 LabPod 호스트에서 실행 중인 서버를 조작할 때 이 명령어를 사용합니다. 로그인한 계정의 권한으로만 동작하므로 sudo가 필요하지 않으며 관리자 명령어를 대신할 수는 없습니다.

로그인과 서버 선택

labpod login https://lab-gpu.example.local --user kim
labpod whoami
labpod logout

비밀번호는 프롬프트에서 입력합니다. 대화형 파이프라인에서는 표준 입력으로 전달할 수도 있습니다. 세션은 서버별로 ~/.config/labpod/client.json에 저장됩니다. 디렉터리 권한은 0700, 파일 권한은 0600입니다. 마지막으로 사용한 서버가 기본 서버가 되며, 다른 저장 서버를 대상으로 하려면 --server <url>을 사용합니다.

세션의 기본 만료 시간은 7일입니다. 운영자는 서버의 LABPOD_SESSION_TTL 값을 바꿀 수 있습니다. 명령어가 종료 코드 3을 반환하면 다시 로그인하세요.

자체 서명 HTTPS 서버에서는 운영자에게 지문을 받아 로그인할 때 고정합니다:

labpod login https://lab-gpu.example.local --user kim --tls-fingerprint <sha256>

이후 연결할 때 클라이언트가 이 지문을 확인합니다. TLS 검증을 끄는 옵션은 제공하지 않습니다.

워크스페이스

labpod ws list
labpod ws capacity
labpod ws create --template tmpl-pytorch-jupyterlab --name train1 --gpu-count 1
labpod ws start <workspace-id>
labpod ws logs <workspace-id> --tail 200
labpod ws stop <workspace-id>
labpod ws delete <workspace-id> --yes

ws create는 지정한 리소스 플래그만 서버에 전달하므로 생략한 값에는 템플릿 기본값이 적용됩니다. CPU, 메모리, GPU, 환경 변수, 런처, 로그 옵션은 labpod ws --help에서 확인하세요.

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

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 template list
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 status <template-id>
labpod image pull <template-id> --wait
labpod image build <template-id> --wait
labpod image builds

템플릿 정의를 자동화하려면 template create --file <spec.json|->와 template edit <id> --file <patch.json|->를 사용하세요. -는 표준 입력에서 JSON을 읽습니다. 가져온 템플릿은 검토할 수 있도록 비활성화된 상태로 생성됩니다. Dockerfile 기반으로 복제하거나 가져온 템플릿은 build를 마친 뒤에 활성화해야 합니다.

워크스페이스를 시작할 때 없는 이미지를 pull하거나 build하지는 않습니다. 레지스트리 이미지는 image pull로 준비하고 Dockerfile 기반 템플릿은 image build로 준비한 뒤 다시 시작하세요. image pull과 image build에는 서버 관리자가 설정한 레지스트리 및 약관 규칙이 적용됩니다.

개인 액세스 토큰

개인 액세스 토큰(PAT)을 사용하면 CLI, 스크립트, LLM 에이전트가 대화형 비밀번호 로그인 없이 LabPod 서버에 인증할 수 있습니다. labpod token으로 토큰을 발급·조회·폐기합니다:

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

새 토큰의 비밀값은 발급 시 한 번만 출력되며 서버에는 저장되지 않으므로 즉시 복사하세요. 기본 수명은 90일입니다. 토큰은 다음 세 가지 방법 중 하나로 사용합니다:

export LABPOD_TOKEN=labpod_pat_...          # 클라이언트 명령어가 자동으로 사용
labpod login https://lab-gpu.example.local --user kim --token   # PAT를 해당 서버 세션으로 저장
curl -H "Authorization: Bearer $LABPOD_TOKEN" https://lab-gpu.example.local/api/workspaces

토큰은 발급한 사용자와 동일한 권한을 가지므로 해당 사용자의 워크스페이스, 템플릿, 이미지를 다룰 수 있지만 관리자 작업은 수행할 수 없습니다. 토큰 자체를 관리하려면 항상 비밀번호 세션 (labpod login)이 필요하며, PAT로는 토큰을 발급하거나 폐기할 수 없습니다.

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

JSON 출력과 종료 코드

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

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

template export는 tar 파일을 쓰므로 예외적으로 --json을 사용할 수 없습니다. 종료 코드는 성공 시 0, API 또는 네트워크 오류 및 확인 취소 시 1, 잘못된 사용법에는 2, 로그인하지 않았거나 세션이 만료된 경우에는 3입니다.

`labpod admin`

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

하위 명령어	기능
`migrate`	보류 중인 데이터베이스 스키마 마이그레이션 적용 (멱등성)
`create-user <name>`	LabPod 계정 생성; Linux 계정이 없으면 프로비저닝
`set-password <name>`	LabPod 비밀번호 교체 (DB만, Linux 비밀번호 아님)
`list-users`	슈퍼유저 및 비활성화 플래그와 함께 모든 사용자 출력
`db-path`	이 실행에 대한 결정된 데이터베이스 경로 출력
`doctor`	호스트 전제 조건 확인 및 수정 사항 보고
`backup --out <path>`	명시적 파일로 일회성 스냅샷
`backup --dir <dir> --retention <N>`	타임스탬프가 있는 스냅샷; 최신 N개로 정리
`restore <path> [--yes]`	라이브 DB에 스냅샷 복사 (서비스를 먼저 중지하세요)
`tls-fingerprint`	서빙 TLS 인증서의 SHA-256 지문 출력
`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에서 비밀번호를 읽습니다. 대화형으로 입력하거나 파이프로 넘길 수 있습니다:

아래 예시는 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에서 지원하지 않습니다. 해당 번들은 /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

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