REST API와 curl로 VPS 관리하기: 상태, 전원, 재설치, 갱신

API로 서버를 주문하는 데는 요청 한 번이면 됩니다. 이 내용은 API 호출 4번으로 VPS 주문하기에 있습니다. 이 페이지는 그 이후의 모든 것을 다룹니다. 평소 대시보드에서 클릭하던 일상 작업을 스크립트에 붙여 넣을 수 있는 curl 명령으로 정리했습니다.

아래 명령은 모두 게시 전에 저희 API에 실행해 보았고, 응답은 돌아온 결과를 줄인 것입니다.

준비

변수 두 개로 명령을 짧게 유지합니다.

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

토큰은 POST /auth/register 또는 대시보드의 Settings → API tokens에서 받습니다. 다른 사람도 그 머신을 쓴다면 셸 기록에 남기지 마세요. export EQVPS_TOKEN=$(cat ~/.eqvps_token)로 파일에서 읽으면 충분합니다.

서버 찾기

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

각 항목에는 47HZ7YF 같은 id가 있습니다. 다른 모든 호출에서 쓰는 서비스 코드입니다. 다음은 서버 한 대의 전체 정보입니다.

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access는 로그인 방법을 알려 줍니다. 전용 IPv4가 있는 요금제에서는 포트가 22이고, NAT 요금제에서는 개인 전달 포트입니다. 이 호출은 읽기만 하므로 루프로 확인해도 안전합니다.

SSH 키 없이 주문했다면 root 비밀번호가 한 번 표시됩니다.

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

서버가 아직 부팅 중이면 응답은 password_pending이고, 일회성 표시는 소진되지 않습니다. 30초쯤 기다렸다가 다시 요청하세요.

전원: start, stop, reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action은 start, stop, reboot 중 하나입니다. 아직 활성화되지 않은 서버(생성 중이거나 미납으로 정지됨)는 409 Service is not active로 응답합니다. 스크립트 오류가 아닙니다. 먼저 status를 확인하세요.

지표

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, 메모리, 네트워크, 디스크를 시계열로 제공합니다. timeframe은 hour(기본), day, week, month입니다. 디스크가 계속 늘어날 때 알려 주는 cron 작업에 유용합니다. 현재 결제 주기의 트래픽 카운터는 속도와 트래픽 확인에 있습니다.

서버 이름 변경

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

새 이름은 게스트 에이전트가 실행 중인 시스템 안에 적용하며, Linux에서는 재부팅이 필요 없습니다. 서버가 중지되어 있거나 qemu-guest-agent를 제거했다면 호출은 409 agent_unavailable을 반환하고 아무것도 바뀌지 않습니다.

OS 재설치

이 작업은 디스크를 지웁니다. API는 confirm에 서버의 현재 호스트 이름을 입력하도록 요구하므로, 서비스 id가 잘못된 스크립트가 엉뚱한 머신을 지울 수 없습니다.

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id는 GET /products의 요금제 available_os 목록이나 서버 자체의 상세 정보에서 가져옵니다. 재설치는 백그라운드에서 진행되니 status가 다시 active가 될 때까지 GET /services/{id}를 확인하세요.

갱신과 잔액

서버는 선불 잔액에서 매달 갱신됩니다. 이 서버의 더 긴 기간 요금을 보려면:

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

예를 들어 3개월을 한 번의 호출로 미리 결제하려면:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months는 1, 3, 6, 12이며, 12는 할인된 연간 가격으로 청구됩니다. 응답에는 paid_from_balance: true와 새 만료일이 담깁니다. 잔액이 금액을 충당하지 못하면 아무것도 청구되지 않고, paid_from_balance: false와 함께 해당 청구서의 checkout_url을 받습니다. 잔액을 충전한 뒤 POST $API/invoices/{invoice_id}/pay로 그 청구서를 잔액에서 결제할 수 있습니다. 여전히 부족하면 같은 종류의 checkout_url을 반환하고 아무것도 청구하지 않습니다. 잔액 확인과 충전:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

충전 응답에는 checkout_url이 들어 있습니다. 암호화폐 결제로, Base, Ethereum, Polygon의 USDT, USDC, ETH를 씁니다. 결제가 온체인에서 확인되면 잔액에 반영됩니다. 결제는 지갑을 갖고 있지 않은 한 스크립트가 대신할 수 없는 유일한 단계입니다.

Monero도 되지만, 수동 확인을 거치는 잔액 충전으로만 가능합니다. XMR을 보내고 트랜잭션 id를 제출하면 확인 후 반영합니다. Monero로 결제하기를 참고하세요.

해지, 그리고 마음 바꾸기

안전한 해지는 결제한 기간이 끝날 때까지 서버를 그대로 두고 단지 갱신하지 않습니다.

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason은 필수입니다. 몇 단어면 충분합니다. 기한 전에 마음이 바뀌었다면:

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

"type": "immediate"도 있습니다. 서버와 데이터를 즉시 삭제하고, "confirm": "<hostname>"이 필요하며, 되돌릴 수 없습니다. 정말로 원하는 게 아니라면 end_of_period를 쓰세요.

토큰 유지하기

새 토큰은 기본 1년간 유효합니다. 인증된 모든 응답에는 X-Token-Expires-At 헤더가 붙어 있어 스크립트가 미리 알아챌 수 있습니다. 토큰을 새것으로 교체하려면:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

기존 토큰은 즉시 작동을 멈추니, 다른 작업을 하기 전에 새 토큰을 저장하세요.

처리해 둘 만한 오류

스크립트 대신 AI 클라이언트에서 하시나요? 같은 작업이 MCP 도구로도 있습니다. AI 에이전트가 MCP로 자기 VPS를 관리하는 방법과 API 레퍼런스를 참고하세요. 아직 서버가 없다면 요금제를 고르세요.