코딩 에이전트용 VPS 권장 사양 및 RAM 용량 가이드

코딩 에이전트용 VPS에는 어느 정도의 RAM이 필요한가?

리포지토리에서 상시 가동되는 코딩 에이전트 하나를 운영하려면 최소 4 GB의 RAM과 2 vCPU로 시작하십시오. 언어 서버나 Docker 빌드가 세션에 추가되는 즉시 8 GB 및 4 vCPU로 사양을 높여야 하며, 대부분의 리포지토리에서는 첫날부터 이러한 환경이 필요합니다. 에이전트 프로세스 자체는 가볍지만, 에이전트가 사용자를 대신해 구동하는 툴체인이 시스템 자원을 점유하기 때문입니다.

[
  {
    "plan": "Minimum viable",
    "ram_gb": 4,
    "vcpu": 2,
    "disk_gb": 50
  },
  {
    "plan": "Comfortable",
    "ram_gb": 8,
    "vcpu": 4,
    "disk_gb": 100
  },
  {
    "plan": "Team, 4 sessions",
    "ram_gb": 16,
    "vcpu": 8,
    "disk_gb": 200
  }
]

위의 모든 기준은 모델이 네트워크를 통해 호출하는 API 뒤의 다른 곳에서 실행된다는 전제하에 작성되었습니다. 이 전제가 전체 사양 결정의 핵심이므로, 가장 먼저 이 부분을 확정하십시오.

에이전트를 실행 중입니까, 아니면 모델을 실행 중입니까?

클라우드 모델을 호출하는 코딩 에이전트는 셸이 연결된 네트워크 클라이언트입니다. 이 에이전트는 파일과 계획을 API로 전송하고 응답을 기다린 뒤, 로컬에서 파일을 수정하고 명령을 실행합니다. 대기 중에는 CPU를 거의 사용하지 않습니다. 에이전트 자체의 메모리 사용량은 수백 MB 수준이므로, 적당한 사양의 CPU를 갖춘 장비가 적합합니다.

모델을 직접 실행하는 것은 다른 하드웨어에서 구동되는 다른 제품입니다. 모델 가중치는 서버가 켜져 있는 동안 메모리에 상주합니다. 4비트로 양자화된 70억 파라미터 모델은 컨텍스트 길이에 따라 증가하는 키/값 캐시를 제외하고도 가중치만 약 5 GB의 메모리가 필요합니다. CPU만 사용할 경우 공유 vCPU는 초당 몇 개의 토큰만 생성할 수 있습니다. 에이전트 작업 하나가 수천 개의 토큰을 생성할 수 있으므로, API를 사용하면 1분 미만으로 끝날 작업이 로컬에서는 거의 1시간이 걸립니다. 이러한 방식이 목적이라면 VRAM(GPU의 비디오 메모리) 용량을 기준으로 장비를 선정하고, 이 페이지 대신 GPU가 포함된 VPS의 실제 성능에 관한 내용을 읽어보시기 바랍니다.

아래의 모든 내용은 클라우드 모델을 사용하는 경우를 가정합니다.

메모리를 실제로 사용하는 요소

[
  {
    "label": "Agent CLI process, idle",
    "typical_mb": 250,
    "peak_mb": 600
  },
  {
    "label": "TypeScript language server",
    "typical_mb": 700,
    "peak_mb": 2000
  },
  {
    "label": "rust-analyzer, large workspace",
    "typical_mb": 1200,
    "peak_mb": 4000
  },
  {
    "label": "Headless Chrome, one tab",
    "typical_mb": 350,
    "peak_mb": 900
  },
  {
    "label": "Node test run, 4 workers",
    "typical_mb": 1600,
    "peak_mb": 3000
  },
  {
    "label": "Docker image build",
    "typical_mb": 800,
    "peak_mb": 2500
  }
]

위 수치는 중간 규모 프로젝트에서 일반적으로 발표되는 값입니다. 이를 절대적인 기준이 아니라 대략적인 경향으로 이해하십시오.

해당 차트는 6개의 행을 포함하며, 에이전트는 가장 적은 메모리를 사용합니다. 에이전트는 대화 세션과 작은 파일 캐시만 유지하므로 유휴 상태일 때 250 MB 근처를 유지합니다. TypeScript 언어 서버는 인덱싱 과정에서 2000 MB 정도에 도달합니다. 이는 tsconfig.json에서 접근 가능한 모든 파일의 타입 그래프를 생성하고, 이후 요청에 빠르게 응답하기 위해 해당 그래프를 메모리에 상주시키기 때문입니다. rust-analyzer는 같은 이유로 대규모 워크스페이스에서 워크스페이스 내 모든 crate를 처리하며 흔히 4000 MB를 상회합니다.

Headless Chrome은 브라우저와 탭 하나당 약 350 MB를 소모하며, 탭이 추가될 때마다 별도의 운영체제 프로세스가 생성됩니다. 4개의 워커를 사용하는 Node 테스트 실행은 4개의 Node 프로세스를 생성하므로 3000 MB 근처에서 정점을 찍습니다. Docker 이미지 빌드는 컨테이너 내부에서 프로젝트 자체 컴파일러를 실행하고 데몬이 레이어를 기록하므로 2500 MB 근처에서 최대치를 기록합니다.

sudo apt update && sudo apt install -y time
/usr/bin/time -v -o /tmp/build.rusage npm run build
grep "Maximum resident set size" /tmp/build.rusage

free -h의 free 열이 아닌 available 열을 확인하십시오. Linux는 남는 모든 페이지를 디스크 캐시로 사용하므로, 정상적으로 작동하는 시스템에서도 free는 작게 나타나며 이는 아무런 정보를 제공하지 않습니다. available은 새로운 프로세스가 실제로 할당받을 수 있는 메모리 양을 나타냅니다.

작동 가능한 세 가지 구성

최소 사양: 4 GB RAM, 2 vCPU, 50 GB 디스크. 에이전트 세션 1개, 리포지토리 1개, 언어 서버 1개, 그리고 기다릴 의향이 있는 빌드 환경입니다. 이 사양으로도 작동은 하지만, 대규모 테스트 실행과 인덱싱 언어 서버가 겹치는 순간 OOM(Out-of-Memory) 킬러를 마주하게 될 것입니다. 스왑을 추가하고 빌드 워커 수를 제한하십시오.

권장 사양: 8 GB RAM, 4 vCPU, 100 GB 디스크. 에이전트 1개, Docker, 테스트용 헤드리스 브라우저를 포함하며 빌드 급증 시에도 여유가 있습니다. 대부분의 1인 개발자에게 적합한 사양입니다. vCPU 수를 두 배로 늘리면 빌드 대기 시간이 대략 절반으로 줄어들며, 이는 메모리 부족보다 훨씬 더 자주 체감되는 성능 향상입니다.

팀 사양: 16 GB RAM, 8 vCPU, 200 GB 디스크. 4개의 동시 세션을 지원하며, 각 세션은 고유한 체크아웃과 툴체인을 가집니다. 피크 타임에 맞춰 사양을 결정하십시오. 유휴 상태인 에이전트 4개는 비용이 거의 들지 않지만, 4개의 테스트가 동시에 실행되면 위 표의 피크 사양보다 4배의 자원이 필요하기 때문입니다.

2026년 8월 기준으로, 첫 번째 행에서 마지막 행으로 넘어가는 비용은 연간 VPS 결제 시 월간 가격의 약 4배 수준입니다. 최하위 사양은 월간 한 자릿수 달러, 최상위 사양은 수십 달러 정도입니다. 가격은 변동될 수 있으므로 계획을 세우기 전에 현재 목록을 확인하십시오. 서버 비용은 전체 비용 중 큰 비중을 차지하지 않는 경우가 많습니다. 에이전트를 매일 사용하는 경우, 모델 API 비용이 서버 비용을 금방 추월하게 됩니다. 따라서 서버 사양을 줄이기 전에 에이전트의 최대 사용 비용을 제한하십시오. 빌드 자체에 대해서는 VPS에서 코딩 에이전트를 실행하기 위한 가이드를 통해 계정 설정 및 연결 종료 후 세션 유지 방법을 확인할 수 있습니다.

RAM이 부족해지기 전에 디스크 공간이 먼저 고갈되는 이유

[
  {
    "label": "Ubuntu 24.04 base and toolchain",
    "typical_gb": 6
  },
  {
    "label": "One JS monorepo checkout",
    "typical_gb": 3
  },
  {
    "label": "node_modules across 3 branches",
    "typical_gb": 4
  },
  {
    "label": "Docker images and build cache",
    "typical_gb": 20
  },
  {
    "label": "Agent logs and journal, 90 days",
    "typical_gb": 2
  }
]

이 항목들을 모두 합산하면 50 GB 디스크는 코드를 한 줄도 작성하기 전에 거의 가득 차게 됩니다. 가장 큰 단일 항목은 약 20 GB를 차지하는 Docker입니다. BuildKit은 사용자가 중단하라고 지시하기 전까지 모든 빌드의 중간 레이어를 전부 보관하기 때문입니다.

docker system df
docker builder prune --filter until=168h

docker system df은 카테고리별로 회수 가능한 공간을 출력하므로, 실행 전후에 확인하십시오. until=168h 필터는 일주일이 지난 빌드 캐시를 삭제하고 이번 주 캐시만 유지하는데, 이는 여전히 시간을 절약해 주는 캐시입니다. docker image prune -a는 더 나아가 컨테이너가 사용하지 않는 모든 이미지를 제거하므로, 다음 빌드 시 다시 이미지를 내려받아야 할 수 있습니다.

Node 프로젝트는 더 기이한 방식으로 실패합니다. npm install은 수십만 개의 작은 파일을 생성하므로, df -h은 여전히 수 GB의 여유 공간이 있다고 보고하더라도 파일시스템의 inode가 고갈될 수 있습니다. 이 경우 디스크가 절반쯤 비어 있는 것처럼 보여도 쓰기 작업은 No space left on device 오류와 함께 실패합니다.

df -h /
df -i /

IUse%의 값이 100이라면, 더 이상 사용하지 않는 브랜치의 node_modules 디렉터리를 삭제하십시오. 또는 각 패키지 버전을 한 번만 저장하고 각 프로젝트에 하드 링크로 연결하는 pnpm로 전환하십시오.

로그는 조용히 공간을 차지합니다. 상시 가동되는 에이전트는 세션 기록을 작성하며, systemd 저널은 기본적으로 디스크의 일정 비율까지 커집니다.

sudo journalctl --disk-usage
sudo journalctl --vacuum-size=200M
du -xh --max-depth=1 / 2>/dev/null | sort -h | tail

/etc/systemd/journald.conf에서 SystemMaxUse=200M을 설정하고 sudo systemctl restart systemd-journald을 실행하여 해당 제한을 영구적으로 적용하십시오. 일회성 vacuum 작업은 오늘의 공간만 확보할 뿐입니다.

스왑: 스왑의 이점과 숨겨진 위험

스왑은 메모리 사용량이 일시적으로 초과했을 때 프로세스가 즉시 종료되는 대신 속도가 느려지게 하므로 추가할 가치가 있습니다. 스왑 크기는 RAM의 절반 정도로 설정하되 최대 4 GB를 넘지 않는 것이 좋습니다. 빌드 서버라면 그 이상 설정할 이유가 거의 없습니다.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
swapon --show

swapon --show 명령을 실행하면 지정한 크기의 /swapfile이 목록에 나타나야 합니다. /etc/fstab 줄이 없으면 재부팅 후 스왑이 사라지고 서버는 조용히 이전 상태로 돌아갑니다. 만약 fallocate 명령의 결과가 Operation not supported이라면, sudo dd if=/dev/zero of=/swapfile bs=1M count=4096를 사용하여 파일을 생성한 뒤 chmod 단계부터 다시 진행하십시오.

echo 'vm.swappiness = 10' | sudo tee /etc/sysctl.d/99-swappiness.conf
sudo sysctl --system

swappiness 값을 낮게 설정하면 커널은 프로그램 메모리를 디스크로 내보내기 전에 디스크 캐시를 먼저 회수하므로, 언어 서버의 응답성을 유지할 수 있습니다.

이제 스왑이 숨기고 있는 문제를 살펴봅니다. 작업이 서버의 실제 메모리 용량을 초과하면, 커널은 빌드 작업을 수행하는 대신 RAM과 디스크 사이에서 페이지를 이동하는 데 시간을 소비합니다. 프로세스는 종료되지 않지만 모든 작업이 매우 느려지며, CPU는 유휴 상태임에도 load average는 치솟게 됩니다.

vmstat 1 10

si 및 so 열의 숫자가 0이 아닌 상태로 꾸준히 유지된다면 지속적인 스와핑이 발생하고 있다는 의미입니다. 이 경우 해결책은 동시성 작업을 줄이거나 RAM을 증설하는 것이며, 스왑을 더 늘리는 것은 올바른 방법이 아닙니다. 소형 서버에서는 sudo apt install -y zram-tools을 사용하여 RAM 내에 압축된 스왑을 생성할 수 있으며, 설정은 /etc/default/zramswap에서 조정합니다. 이는 스왑 파일보다 훨씬 빠르지만, RAM을 사용하여 RAM을 확보하는 방식이므로 자주 사용하지 않는 페이지를 처리하는 데는 도움이 되지만 실제 작업 메모리가 필요한 빌드 작업에는 효과가 없습니다.

코딩 에이전트가 멈춘 것처럼 보이는 이유

소규모 에이전트 서버에서 가장 잘못 진단되는 장애 유형입니다. 명령어가 아무런 출력도 내놓지 않고 에이전트가 대기 상태에 빠지면 세션이 멈춘 것처럼 보입니다. 실제로는 커널의 OOM(Out-Of-Memory) 킬러가 해당 프로세스를 강제 종료한 것입니다. 프로세스가 SIGKILL 신호를 받았기 때문에 오류 메시지를 출력하거나 로그를 기록하거나 에이전트에게 상황을 알릴 기회가 없었습니다. 에이전트는 빈 결과값과 종료 메시지 부재만을 확인하게 됩니다.

커널은 이 사건을 다음과 같이 기록합니다.

sudo dmesg -T | grep -iE "out of memory|killed process"
sudo journalctl -k -b | grep -i oom

실제 로그 한 줄은 다음과 같습니다.

[Thu Aug  6 11:02:14 2026] Out of memory: Killed process 4711 (node) total-vm:4210880kB, anon-rss:3820104kB, file-rss:0kB, shmem-rss:0kB, UID:1000 pgtables:8236kB oom_score_adj:0

anon-rss은 프로세스가 종료될 당시 점유하고 있던 메모리 양입니다. 어떤 프로세스가 선택되었는지 확인하십시오. 커널은 주로 사용 중인 메모리 양을 기준으로 점수를 매기므로, 시스템 자원을 한계치까지 밀어붙인 빌드 작업 대신 언어 서버나 에이전트 프로세스를 종료하는 경우가 많습니다. 바로 이 때문에 증상이 "에이전트 고장"으로 나타나는 것입니다.

Docker 내부에서는 동일한 이벤트가 더 명확한 흔적을 남깁니다. 컨테이너는 128에 신호 9를 더한 값인 137 코드로 종료됩니다.

docker ps -a
docker inspect "$(docker ps -lq)" | grep -i oomkilled

"OOMKilled": true은 컨테이너가 자체적인 오류로 충돌한 것이 아니라 메모리 제한에 도달했음을 확인해 줍니다.

해결책은 리소스를 많이 소모하는 명령어에 별도의 상한선을 설정하여, 에이전트가 아닌 빌드 프로세스가 먼저 종료되도록 만드는 것입니다.

systemd-run --user --scope -p MemoryMax=4G -- npm run build

이제 빌드 작업은 4 GB에서 강제 종료되고 에이전트는 살아남습니다. 이로써 원인을 알 수 없던 멈춤 현상이 읽기 가능한 종료 코드를 가진 일반적인 명령어 실패로 바뀝니다. 이 설정에는 systemd 사용자 세션이 필요하므로, SSH로만 접속하는 서버라면 loginctl enable-linger $USER를 실행하십시오. MemoryHigh=은 프로세스를 종료하는 대신 해당 임계값에서 속도를 제한합니다. 빌드가 느리게라도 완료되기를 원한다면 이 설정이 더 나은 선택일 수 있습니다.

Compose 메모리 제한 설정

에이전트 도구가 컨테이너에서 실행된다면, Compose 파일에 상한선을 설정하여 모든 실행 시 적용되도록 합니다.

services:
  agent:
    image: node:22-bookworm
    deploy:
      resources:
        limits:
          memory: 2g
          cpus: "1.5"

Docker Compose v2는 일반적인 docker compose up 환경에서도 deploy.resources.limits를 적용하므로, swarm 모드는 필요하지 않습니다. 이전 버전의 mem_limit: 2g 키도 여전히 작동합니다. Compose 메모리 제한 전체 가이드에서는 예약 설정과 컨테이너가 상한선에 도달했을 때 발생하는 상황을 다룹니다. 서버에 Docker가 설치되어 있지 않다면, 먼저 VPS에 Docker 설치를 진행하십시오.

많은 사용자가 흔히 겪는 함정이 하나 있습니다. 2 GB로 제한된 컨테이너라도 호스트의 /proc/meminfo와 CPU 개수를 그대로 읽어 들입니다. 이는 두 정보 모두 네임스페이스로 격리되지 않기 때문입니다. CPU 개수를 기준으로 작업자(worker) 수를 결정하는 테스트 러너는 8개의 vCPU를 가진 호스트의 2 GB 컨테이너 안에서 8개의 작업자를 실행하려다 137번 오류로 종료됩니다. 따라서 수치를 직접 지정해야 합니다.

npx jest --maxWorkers=2
export NODE_OPTIONS=--max-old-space-size=1536

--max-old-space-size는 MB 단위이며 V8 힙의 상한선을 결정합니다. 컨테이너 제한보다 낮은 값으로 설정하면, 프로세스가 갑자기 사라지는 대신 읽을 수 있는 오류 메시지를 Node가 출력합니다.

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

이 메시지는 도달한 제한 수치와 해당 프로세스를 명시하므로 매우 유용합니다. OOM killer는 이러한 정보를 제공하지 않습니다.

한 서버에서 여러 에이전트 세션 실행하기

사용자 기준이 아닌 세션 기준으로 계획을 세워야 합니다. 동일한 저장소에서 두 개의 세션을 실행하면 두 개의 언어 서버, 두 개의 메모리 내 빌드 캐시가 생성되며, 두 에이전트가 동시에 작업을 수행할 경우 테스트도 두 번 실행됩니다. 이것이 팀 단위 행의 메모리 요구량이 16 GB로 증가하는 이유입니다.

한 세션이 폭주하여 서버 전체를 마비시키지 않도록 각 사용자에게 엄격한 제한을 설정하십시오.

id -u alice
sudo mkdir -p /etc/systemd/system/user-1001.slice.d
printf '[Slice]\nMemoryMax=6G\n' | sudo tee /etc/systemd/system/user-1001.slice.d/limit.conf
sudo systemctl daemon-reload
systemctl show user-1001.slice -p MemoryMax

1001을 id -u가 출력한 UID로 교체하십시오. 사용자가 로그인하면 systemctl show은 MemoryMax=6442450944을 출력해야 합니다. 해당 사용자의 세션 내 모든 프로세스가 6 GB를 초과하면 커널이 해당 슬라이스 내의 프로세스를 강제 종료하며, 다른 모든 세션은 정상적으로 작동합니다. 터미널이 아닌 서비스 형태로 실행되는 에이전트의 경우, 대신 MemoryMax=를 unit 파일에 추가하십시오. 이는 에이전트를 상시 실행 서비스로 직접 호스팅할 때 따라야 할 패턴입니다.

FAQ

2 GB RAM으로 코딩 에이전트를 실행하기에 충분합니까?

에이전트 프로세스 자체는 충분하지만, 에이전트가 수행하는 작업까지 고려하면 거의 부족합니다. 에이전트 프로세스는 대략 250 MB를 점유하지만, TypeScript 언어 서버 하나만으로도 중간 규모 저장소에서 2000 MB에 도달할 수 있습니다. 이 경우 2 GB 서버는 즉시 스왑(swap)을 사용하게 됩니다. 2 GB는 설정 파일이나 간단한 스크립트를 수정하는 용도로는 적합합니다. 컴파일이나 테스트 스위트를 실행하는 환경이라면 최소 4 GB를 권장합니다.

VPS에서 코딩 에이전트를 실행하려면 GPU가 필요합니까?

API를 통해 클라우드 모델을 호출하는 방식이라면 필요하지 않습니다. 해당 작업은 네트워크 의존성이 높으므로 일반 CPU VPS가 적합하며, GPU는 높은 비용만 발생시키고 유휴 상태로 남게 됩니다. 모델을 서버 내부에서 직접 실행할 때만 GPU가 필요하며, 이때는 RAM이 아닌 VRAM 용량과 모델 크기가 고려 대상이 됩니다.

에이전트용 VPS에 스왑을 얼마나 추가해야 합니까?

RAM 용량의 절반, 최대 4 GB 정도가 적당합니다. 스왑은 커널이 프로세스를 강제 종료하는 대신 사용 빈도가 낮은 페이지를 디스크로 옮겨 일시적인 메모리 초과 상황을 방지하는 역할을 합니다. 스왑이 실제 사용 가능한 메모리를 늘려주는 것은 아닙니다. 만약 vmstat 1 명령 실행 시 si 및 so 열에서 지속적인 트래픽이 발생한다면, 시스템이 스래싱(thrashing) 상태에 빠진 것이므로 병렬 작업 수를 줄이거나 더 큰 사양의 서버로 이전해야 합니다.

코딩 에이전트가 빌드 도중에 멈추는 이유는 무엇입니까?

빌드 프로세스가 커널의 OOM killer에 의해 강제 종료되었을 가능성이 매우 높습니다. OOM killer는 SIGKILL을 보내기 때문에 별도의 로그가 남지 않으며, 에이전트는 데이터가 채워지지 않는 파이프를 기다리며 멈추게 됩니다. sudo dmesg -T | grep -i "killed process" 명령을 실행하여 프로세스 이름과 anon-rss 값을 확인하십시오. 해결 방법은 systemd-run --user --scope -p MemoryMax=4G 명령으로 빌드 자원을 제한하고 작업자(worker) 수를 줄이거나, 더 높은 RAM 사양의 서버로 업그레이드하는 것입니다.