autodl-cli

비공식. 이 프로젝트는 AutoDL과 제휴, 보증, 후원 관계가 아닙니다. "AutoDL"은 이 도구가 통신하는 플랫폼을 식별하기 위해서만 사용됩니다.

명령줄에서 AutoDL GPU 인스턴스를 관리하세요 — 그리고 코딩 에이전트도 그렇게 할 수 있습니다.

AutoDL의 공식 공개 API를 기반으로 하므로 개발자 토큰은 무기한 유효하며 웹 콘솔이 재설계되어도 아무것도 깨지지 않습니다.

简体中文

왜

AI 에이전트가 작업 중에 GPU 박스가 필요할 때, 그것을 얻을 방법이 없습니다: AutoDL의 인스턴스는 웹 콘솔을 클릭하여 생성됩니다. 이 도구는 에이전트에게 세 가지 진입점을 제공하며, 모두 동일한 핵심을 기반으로 합니다:

모든 명령은 안정적인 스키마와 문서화된 종료 코드를 가진 --json을 지원하므로, 에이전트는 문장을 파싱하지 않고 결과에 따라 분기할 수 있습니다.

Related MCP server: lab-ops

설치

npm install -g @minatoaqukin/autodl-cli   # then: autodl <command>
npx @minatoaqukin/autodl-cli <command>    # or without installing

Node.js 22+가 필요합니다.

대시보드

autodl tui     # or just `autodl` in an interactive terminal

토큰이 아직 없는 머신에서는 로그인 화면이 열리며 두 가지 옵션을 제공합니다 — 토큰 구성 또는 종료. 토큰을 붙여넣으면 저장 전에 API에 대해 검증되고 대시보드에 도달합니다. 구성이 완료되면 autodl은 바로 들어갑니다.

인스턴스의 실시간 테이블: 상태, GPU, 지역, 각 인스턴스가 켜져 있는 시간과 대략적인 비용, 그리고 남은 TTL. 키: ↑↓ 이동, Enter 상세, s 시작, x 중지, c SSH 명령을 클립보드에 복사, Ctrl+D 해제, g GPU 재고, n 새 인스턴스, r 새로고침, q 종료. 해제는 단일 키 대신 Ctrl+D에 있습니다. 인스턴스를 영구적으로 삭제하기 때문입니다.

터미널을 채우고 헤더에 계정 ID와 잔액을 표시합니다. c로 복사하면 SSH 명령만 클립보드에 넣습니다 — 루트 비밀번호는 절대 넣지 않습니다. 어떤 프로세스도 읽을 수 있기 때문입니다. 클립보드 도우미가 없는 곳(SSH 세션, 컨테이너)에서는 OSC 52로 대체하고 그렇게 말합니다. 터미널이 확인하지 않기 때문입니다.

터미널의 대체 화면에서 실행되므로 이미 있는 내용 아래로 스크롤하는 대신 고정된 캔버스를 소유하며, 종료하면 프롬프트와 스크롤백이 그대로 복원됩니다.

AutoDL이 전원 상태로 청구하기 때문에 존재합니다: 비싼 실수는 잘못된 명령이 아니라 아무도 중지하지 않은 인스턴스입니다. 이 화면을 열어두면 그것이 보입니다.

두 가지 의도적인 정직성 제약. 요금은 실행 중인 인스턴스의 스냅샷에서만 알 수 있으므로 중지된 인스턴스는 경과 시간과 돈 없음을 표시합니다 — 숫자를 지어내는 것은 아무것도 표시하지 않는 것보다 나쁩니다. 그리고 요금이 아직 로드되는 동안 총액은 조용히 과소 보고하는 대신 그렇게 말합니다.

TUI는 파이프, CI, 또는 --json에서 실행되지 않습니다: 존재하지 않는 터미널을 차지하는 대신 코드 2와 설명으로 종료됩니다. 대화형 터미널 밖의 단순한 autodl은 이전과 정확히 동일하게 도움말을 출력합니다.

설정

공식 API는 신원 확인된 계정(个人或企业实名认证)의 개발자 토큰이 필요합니다. AutoDL 콘솔 → 设置 → 开发者 Token에서 가져옵니다.

autodl login              # verifies the token, then saves it with 0600 permissions
autodl account            # balance, vouchers, lifetime spend

토큰 우선순위: --token › AUTODL_TOKEN › ~/.config/autodl-cli/config.json.

빠른 시작

# Rent a GPU that shuts itself off after two hours, and wait until it's ready
autodl create --gpu 4090 --ttl 2h --wait

# Work with it
autodl ls
autodl ssh pro-76419909953e                    # interactive login
autodl exec pro-76419909953e "nvidia-smi"      # one-off command, remote exit code
autodl push pro-76419909953e ./src /root/work  # SFTP upload
autodl pull pro-76419909953e /root/work/out .  # SFTP download

# Stop paying
autodl stop pro-76419909953e
autodl rm pro-76419909953e --yes               # irreversible: wipes all data

또는 한 단어로 전체를 수행하세요:

autodl run "python train.py" \
  --gpu 4090 --sync ./ --pull /root/autodl-cli/checkpoints --ttl 4h

그것은 인스턴스를 생성하고, 기다리고, 코드를 업로드하고, 명령의 출력을 스트리밍하고, 결과를 다운로드하고, 인스턴스를 전원을 끕니다 — Ctrl-C를 포함하여.

에이전트에서 사용

Claude Code

claude mcp add autodl -- npx -y @minatoaqukin/autodl-cli mcp

Cursor / Cline / 모든 MCP 클라이언트

{
  "mcpServers": {
    "autodl": {
      "command": "npx",
      "args": ["-y", "@minatoaqukin/autodl-cli", "mcp"],
      "env": { "AUTODL_TOKEN": "your-token" }
    }
  }
}

노출된 도구: autodl_account_info, autodl_list_instances, autodl_get_instance, autodl_create_instance, autodl_power_on, autodl_power_off, autodl_release_instance, autodl_exec, autodl_upload, autodl_download, autodl_run, autodl_list_gpu_specs, autodl_list_images, autodl_save_image, autodl_sweep_expired. 또한 autodl://instances 리소스가 있습니다.

MCP 기본값은 CLI보다 의도적으로 더 엄격합니다. 아무도 지켜보지 않기 때문입니다: 더 길게 요청하지 않으면 2시간 TTL이 적용되고, 해제는 명시적인 confirm: true가 필요하며, 비밀번호는 요청하지 않으면 수정되어 반환됩니다.

셸 / CI

autodl ls --json | jq -r '.data[] | select(.status=="running") | .uuid'

Git 프로젝트 배포

# Rent a box, clone, auto-install dependencies, run it, then stop the instance
autodl deploy owner/repo --gpu 4090 --start "python train.py" --ttl 4h

# Long-running service: background it and keep the instance up
autodl deploy owner/repo --gpu 4090 --start "python app.py" --detach

# Come back later — powers the same box on and `git pull`s, no rebuild
autodl deploy owner/repo --instance pro-76419909953e --start "python train.py"

deploy는 run과 한 가지 의도적인 차이가 있습니다: 끝에서 인스턴스를 해제하는 대신 중지합니다. 중지된 인스턴스는 디스크를 유지하므로 다음 배포는 이미 구축한 환경을 재사용합니다. --on-finish release는 이를 선택 해제합니다.

코드는 /root/autodl-tmp/<repo> — 데이터 디스크에 배치됩니다. AutoDL의 시스템 디스크는 고정 30GB이며 저장된 이미지에도 포함됩니다. 데이터 디스크는 별도로, 더 빠르고 확장 가능합니다. 알아야 할 절충: 데이터 디스크 내용은 이미지를 저장할 때 포함되지 않으므로 환경은 시스템 디스크에, 코드는 여기에 두십시오.

의존성은 이 순서로 자동 감지되며, 첫 번째 적중이 우선합니다 — environment.yml → requirements.txt → pyproject.toml → package-lock.json/package.json. --setup "<cmd>"로 재정의하거나 --no-setup으로 건너뜁니다.

원격 명령은 로그인 셸을 통해 실행됩니다. AutoDL 이미지는 python, pip 및 conda를 /root/miniconda3/bin에 유지하며, 이는 로그인 프로필을 통해서만 PATH에 도달합니다 — 일반 비대화형 ssh host "pip install ..."는 127로 종료됩니다. 이것은 autodl exec에도 적용되므로 직접 autodl ssh로 들어갈 때와 동일하게 동작합니다.

GitHub 또는 HuggingFace에서 클론하면 AutoDL의 학술 프록시(source /etc/network_turbo)가 자동으로 활성화됩니다. Gitee는 국내용이므로 건너뜁니다. --no-accel은 비활성화합니다. AutoDL은 프록시가 "학술용이며 안정성을 보장하지 않는다"고 언급합니다.

비공개 저장소: --git-token 또는 환경의 GIT_TOKEN / GITHUB_TOKEN. 토큰은 로그 라인, 오류 메시지, --json 출력 또는 체크아웃의 저장된 git 원격에 절대 도달하지 않습니다.

GPU 재고 확인

autodl stock --gpu 4090        # where are the free cards
autodl stock                   # everything, everywhere

이 표를 주의 깊게 읽으십시오 — 숫자는 보이는 것보다 권위가 덜합니다. 이 숫자는 AutoDL의 탄력적 배포 재고 엔드포인트에서 가져온 것으로, 존재하는 유일한 용량 API이며 Pro 인스턴스 가용성을 추적하지 않습니다. 2026-08-23에 측정: westDC3에서 140개의 유휴 RTX 4090D를 보고했지만, 거기서 Pro 인스턴스를 생성하려고 하면 *"暂无库存"*라고 응답했습니다 — 그리고 지역 제약이 없는 동일한 요청은 성공하여 beijingDC2에 배치되었습니다.

두 가지 결과가 모두 도구에 내장되어 있습니다:

• 인스턴스 생성은 자체적으로 지역을 좁히지 않습니다. data_center_list를 생략하면 AutoDL에 가장 넓은 선택권을 주며, 경험적으로 가장 자주 성공합니다.

• Pro 인스턴스를 수락하는 지역은 두 곳뿐입니다: westDC3 (西北B区) 및 beijingDC2 (北京B区). 재고 표의 다른 9개 지역은 탄력적 배포 전용입니다. --region에 전달하면 AutoDL의 불투명한 "请求参数错误"로 나중에 실패하는 대신 사전에 거부됩니다. 可建Pro 열은 어느 것이 어느 것인지 표시합니다.

비용 가드

AutoDL은 순수하게 전원 상태로 청구합니다. 한 시간 전에 훈련을 마친 인스턴스는 100% 사용률의 인스턴스와 정확히 같은 비용이 듭니다. 이것은 무인 에이전트가 실제 돈을 낭비하는 가장 쉬운 방법이므로 보호는 선택 사항이 아니라 내장되어 있습니다.

세 가지 계층:

1. 인스턴스 내부. --ttl 2h는 start_command를 통해 박스 자체에 분리된 sleep && shutdown을 장착합니다. 이 CLI가 종료되거나, 노트북이 절전 모드이거나, 네트워크가 끊겨도 실행됩니다. 이것이 실제로 지갑을 보호하는 계층입니다.

2. 로컬 원장. 모든 명령은 기회적으로 TTL이 지난 인스턴스를 정리하고 전원을 끕니다. 계층 1이 처리할 수 없는 경우를 잡습니다 — 조용히 실패한 start_command 또는 새 타이머 없이 수동으로 전원을 켠 경우.

3. 유휴 감지. autodl guard idle <id>는 SSH를 통해 GPU 사용률을 샘플링하고 지속적인 침체 후 종료합니다.

autodl guard ttl pro-xxx 2h     # arm/re-arm on a running instance
autodl guard cancel pro-xxx     # disarm
autodl guard list               # what this machine is tracking
autodl guard sweep              # reclaim everything past its TTL now
autodl guard idle pro-xxx --threshold 5 --samples 6 --interval 1m

잔액 게이트는 지갑이 --min-balance(기본 ¥5) 미만일 때 인스턴스 생성을 거부합니다. AutoDL은 잔액이 0이 되는 순간 인스턴스를 회수하지 않습니다 — 데이터를 보호하기 위해 유지합니다 — 따라서 낮은 잔액은 깔끔한 실패가 아니라 멈춘, 사용할 수 없는 인스턴스로 변합니다.

에이전트 계약

부 버전에서 안정적입니다. 주요 변경은 메이저가 필요합니다.

--json 모드의 stdout은 순수 JSON입니다. 진행 상황, 프롬프트 및 경고는 모두 stderr로 이동하므로 autodl ... --json | jq는 항상 안전합니다.

// success
{ "ok": true, "data": { /* ... */ } }

// failure
{ "ok": false, "error": { "code": "NO_STOCK", "message": "…", "hint": "…", "requestId": "…" } }

autodl exec 및 autodl run은 대신 원격 명령의 종료 코드로 종료되므로 autodl exec box "make test" && deploy는 예상대로 동작합니다.

명령

전역 플래그: --json, --yes, --token, --base-url, --lang zh|en, --verbose, --no-color, --no-sweep.

push와 pull은 .git, node_modules, __pycache__, .venv 등을 건너뛴 다음, .autodlignore가 있으면 이를 적용하고, 없으면 .gitignore로 대체합니다.

SDK

import {
  AutoDLClient,
  createInstance,
  execCommand,
  powerOffInstance,
  waitForRunning,
} from "@minatoaqukin/autodl-cli";

const client = new AutoDLClient({ token: process.env.AUTODL_TOKEN! });

const uuid = await createInstance(client, {
  gpuSpec: "v-48g",
  gpuNum: 1,
  imageUuid: "base-image-l2t43iu6uk",
  cudaFrom: 118,
});

await waitForRunning(client, uuid);
const { stdout } = await execCommand(client, uuid, "nvidia-smi");
console.log(stdout);
await powerOffInstance(client, uuid);

패키지 루트에서 다시 내보내는 모든 것은 공개 API입니다. 가격은 위안(number) 단위로, 타임스탬프는 ISO 문자열로 도착하며, Go의 sql.NullTime 형태는 string | null로 평탄화됩니다.

공식 API로 할 수 없는 것

이것들은 이 도구의 한계가 아니라 AutoDL의 한계입니다. 미리 알아두면 많은 혼란을 줄일 수 있습니다:

• 선불제(Pay-as-you-go)만 지원. 일/주/월 요금제와 갱신 엔드포인트가 없습니다.

• Pro 인스턴스만 지원. autodl gpus의 7가지 사양 — 더 저렴한 표준 인스턴스는 공개 API로 접근할 수 없습니다.

• Pro에 대한 실용적인 재고 조회 불가. 유일한 용량 엔드포인트는 탄력적 배포 재고를 보고하는데, 이는 Pro 가용성과 분명히 일치하지 않습니다(위 참조). 생성은 사실상 맹목적인 시도입니다. 용량이 없으면 종료 코드 6과 함께 다른 사양을 시도하게 됩니다.

• Pro 인스턴스를 수용하는 리전은 두 곳뿐입니다: westDC3 및 beijingDC2.

• 아직 CPU 전용 부팅은 불가. AutoDL 자체의 표현도 의도적으로 잠정적입니다: payload는 "gpu：有卡开机, 暂不支持API以无卡模式开机"로 문서화되어 있습니다 — 아직 지원되지 않는다는 뜻이지, 영원히 안 된다는 뜻이 아닙니다. 2026-08-24에 실제 인스턴스에서 확인: cpu, no_gpu, nogpu, cpu_only, cpu-only, none 모두 ServerError | 不支持的启动模式을 반환하며, 빈 payload는 수락되지만 GPU가 연결된 상태로 부팅됩니다(start_mode: "gpu"). 그동안은 웹 콘솔에서 ¥0.1/hr 무카드 모드를 사용하세요. 이 도구는 API가 지원하게 되면 노출할 것입니다.

• 신원 인증 필수. API가 전혀 응답하기 전에 필요합니다.

• 누락된 작업: 이름 변경, 예약 종료, 크기 조정, 마이그레이션, 시스템 리셋.

• SSH 자격 증명은 전원 주기마다 변경될 수 있음 — 포트 및 루트 비밀번호 모두. AutoDL은 인스턴스를 다른 머신으로 재스케줄할 수 있습니다. 항상 발생하는 것은 아니며(실제 중지/시작에서 둘 다 동일하게 유지되는 것이 관찰됨), 이것이 바로 캐싱을 위험하게 만드는 이유입니다: 오래된 값이 버그가 드러날 때까지 충분히 자주 작동해서 숨겨버립니다. 이 도구는 모든 연결 시마다 이를 다시 읽으므로 신경 쓸 필요가 없습니다.

• running이 sshd 준비를 의미하지는 않음. 새로 생성된 인스턴스는 연결을 수락하기 전에 running을 보고합니다. 여기서 연결 시도는 연속으로 발사되지 않고 간격을 두고 이루어집니다.

• 비대화형 SSH 세션에는 PATH가 거의 없음. python, pip, conda가 없습니다 — 이들은 /root/miniconda3/bin에 있으며 로그인 프로필을 통해서만 제공됩니다. 따라서 여기의 모든 원격 명령은 bash -lc로 실행됩니다.

• 릴리스하려면 종료가 완료되어야 하며, 이미 중지 중인 인스턴스에 두 번째 power_off를 실행하면 오류입니다. 둘 다 내부적으로 처리됩니다.

또한 알아두면 좋은 점: 15일 연속 종료 상태로 방치된 인스턴스는 릴리스되고 데이터가 삭제됩니다.

2026-08-23에 실제 API로 검증됨: 4090D에서 전체 수명 주기(생성 → SSH 실행 → SFTP 왕복 → 중지 → 시작 → 다시 실행 → 릴리스), 총 비용 ¥0.10.

GPU 사양, 리전 및 기본 이미지 테이블은 API가 카탈로그 엔드포인트를 노출하지 않기 때문에 내장되어 있습니다. AutoDL이 이를 변경하면 이슈를 열어 주세요.

개발

npm install
npm run build
npm test            # 325 tests, no network access, no cost
npm run lint
npm run typecheck

실제 종단 간 테스트는 실제 GPU를 임대하고 실제 비용이 들기 때문에 옵트인 방식입니다:

AUTODL_E2E=1 AUTODL_TOKEN=<token> npm run test:e2e

실패 시에도 항상 afterAll에서 인스턴스의 전원을 끕니다. 릴리스도 하려면 AUTODL_E2E_RELEASE=1을 추가하세요.

기여

이슈와 PR 환영합니다 — CONTRIBUTING.md를 참조하세요. 특히 가치 있는 것: 정적 카탈로그에 대한 수정, 그리고 아직 매핑하지 않은 실제 API 오류 코드(AutoDL은 이를 문서화하지 않습니다).

라이선스

MIT