VPS에서 OpenCode 설치 및 tmux 실행 방법

OpenCode의 정의 및 설정 개요

OpenCode는 터미널용 오픈 소스 AI 코딩 에이전트입니다. 프로젝트 디렉토리 내에서 실행하며, 터미널 사용자 인터페이스(TUI)를 통해 코드를 읽고, 변경 사항을 제안하며, 파일을 수정하고, 명령어를 실행합니다. MIT 라이선스로 제공되며 75개 이상의 모델 제공업체와 연결됩니다. 2026년 중반 기준 GitHub star 수가 약 165,000개에 달하며, 가장 많은 star를 받은 오픈 소스 코딩 에이전트입니다. VPS에서 OpenCode를 실행하려면 권한이 제한된 전용 사용자를 생성하여 설치해야 합니다. 모델 API key는 별도의 비공개 파일에 저장하며, 연결이 끊겨도 세션이 유지되도록 tmux 내에서 실행해야 합니다. 본 가이드는 이 절차를 순서대로 설명합니다.

명칭 혼동을 방지하기 위한 안내입니다. 공식 저장소는 Anomaly 팀(구 SST)이 관리하는 anomalyco/opencode이며, 이전 프로젝트 경로는 sst/opencode이었습니다. GitHub에는 opencode-ai/opencode라는 이름의 관련 없는 오래된 저장소도 존재하므로, 올바른 프로젝트의 문서를 확인하십시오. 공식 사이트는 opencode.ai입니다.

VPS에서 OpenCode를 실행해야 하는 이유

코딩 에이전트 세션은 실행 시간이 깁니다. OpenCode가 리팩터링이나 테스트 스위트를 처리하는 데 수 분이 소요될 수 있습니다. 노트북에서 실행할 경우, 노트북 덮개를 닫거나 Wi-Fi 연결이 끊기면 작업 도중에 세션이 종료됩니다. VPS에서 tmux를 사용하여 실행하면 연결을 끊은 후에도 에이전트가 작업을 계속합니다. 나중에 다시 연결하여 작업 결과를 확인할 수 있습니다. 이는 tmux를 사용하여 VPS에서 Claude Code를 실행하는 방식과 동일하며, 에이전트를 노트북에서 분리할 때 얻을 수 있는 가장 큰 편의성입니다.

두 번째 이유는 위치입니다. VPS는 배포 대상 코드와 물리적으로 가깝습니다. 리포지토리, 빌드 도구, 테스트 데이터베이스, 그리고 스테이징 환경이 이미 해당 서버나 근처에 존재합니다. 코드를 수정하고 테스트를 실행하는 에이전트는 테스트가 실제로 실행되는 머신에서 작동할 때 가장 효율적입니다. 또한 사용자가 제어하는 서버이므로, 다음 섹션에서 설명하듯 에이전트에게 의도적으로 격리된 환경을 제공할 수 있습니다.

도구를 선택 중이라면, Aider와 Goose를 포함하여 다양한 도구를 비교한 VPS에서 코딩 AI 에이전트 실행하기를 참고하십시오.

OpenCode 전용 사용자 생성

현실적인 상황을 고려해야 합니다. 코딩 에이전트는 파일을 수정하고 명령어를 실행합니다. 이것이 에이전트의 역할이지만 동시에 보안 위험 요소입니다. OpenCode는 빌드, 테스트 및 작업에 필요한 모든 shell command를 실행합니다. 모델의 판단력은 뛰어나지만 완벽하지는 않습니다. 에이전트가 실행되는 계정의 권한이 에이전트가 수행할 수 있는 작업의 한계가 됩니다. 따라서 root 계정으로 실행하지 마십시오. 서버를 관리하는 계정과 동일한 계정으로 실행하지 마십시오.

Background agent와 달리 OpenCode는 대화형(interactive)입니다. 따라서 해당 사용자는 실제 shell과 home directory가 필요합니다.

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

에이전트가 작업할 프로젝트는 해당 사용자가 clone한 /home/opencode 아래에 두십시오. 해당 계정에는 sudo 권한을 부여하지 마십시오. 에이전트가 파괴적인 명령어를 실행하더라도 해당 계정이 소유한 데이터만 손상됩니다. 이는 unprivileged user로 서비스를 실행하는 것과 동일한 논리입니다. 또한 git repository 내부에서 작업하십시오. repository를 사용하면 잘못된 수정이 발생해도 데이터 손실 대신 git revert 상태로 복구할 수 있습니다.

OpenCode 설치

이 프로젝트는 두 가지 설치 방법을 제공합니다. 설치 스크립트를 사용하는 것이 가장 빠릅니다. opencode 사용자로 스크립트를 실행하면 모든 파일이 해당 사용자의 홈 디렉토리에 저장됩니다.

curl -fsSL https://opencode.ai/install | bash

다른 모든 경우와 마찬가지로 일반적인 curl | bash 관행을 따릅니다. 중요한 서버에서는 먼저 스크립트를 다운로드하고 내용을 확인한 뒤 실행하십시오. 설치가 완료되면 설치 프로그램이 변경한 PATH를 적용하기 위해 새 셸을 시작하십시오. 그 다음 바이너리 작동 여부를 확인합니다.

opencode --version

패키지 관리자를 선호하고 시스템에 Node.js가 이미 설치되어 있다면, npm을 통해 도구를 시스템 전체에 설치할 수 있습니다. 이 방식은 모든 사용자의 PATH에 opencode 바이너리를 추가합니다.

sudo npm install -g opencode-ai

두 방법 모두 확인 방법은 동일합니다. opencode --version을 실행하면 버전 번호가 출력됩니다. 스크립트로 설치한 후 command not found이 발생하면 현재 셸이 업데이트된 PATH를 아직 읽지 않았음을 의미합니다. 이 경우 로그아웃한 뒤 opencode 사용자로 다시 로그인하십시오.

API key를 private 파일에 저장하십시오

OpenCode는 사용하는 model provider의 key가 필요합니다. 이 key는 비용을 발생시키므로 비밀번호와 같이 취급해야 합니다. mode 600을 사용하여 opencode 사용자만 읽을 수 있는 파일을 생성하십시오. 명령어에 key를 직접 입력하면 shell history에 남게 되므로, 파일에 저장하여 사용하십시오.

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

OpenCode는 표준 provider environment variables를 사용합니다. 따라서 ANTHROPIC_API_KEY=... 또는 해당 provider의 상응하는 변수를 파일에 입력하십시오. agent를 시작하기 전에 다음 명령어로 파일을 shell에 로드하십시오.

set -a; source ~/opencode.env; set +a

OpenCode는 대화형 방식도 제공합니다. TUI 내에서 /connect 명령어를 실행하면 provider 추가 과정을 안내하며, 자격 증명을 사용자의 home 디렉토리에 있는 ~/.local/share/opencode/auth.json에 저장합니다. 이 방식을 사용한다면 chmod 600 ~/.local/share/opencode/auth.json 명령어로 파일이 private 상태인지 확인하십시오. 두 방식 모두 command line에 key가 남지 않도록 합니다. 한 가지 방식을 선택하여 일관되게 사용하십시오.

tmux 내에서 OpenCode 시작하기

tmux를 사용하면 VPS 설정의 가치가 높아집니다. SSH 연결이 종료되어도 tmux 세션은 계속 실행되기 때문입니다. tmux를 시작하고, 프로젝트 디렉토리로 이동한 뒤, 에이전트를 실행하십시오:

tmux new -s opencode
cd ~/my-project
opencode

하단에 프롬프트가 표시되고 인터페이스에 프로젝트 이름이 나타나며 TUI가 실행됩니다. 수행할 작업을 평문으로 입력하면 에이전트가 파일을 읽고 변경 사항을 제안하기 시작합니다. 작업을 중단하려면 Ctrl-b를 누른 후 d를 눌러 세션을 분리(detach)하십시오. 노트북을 닫아도 에이전트는 작업을 계속 수행합니다. 나중에 다시 연결하려면 다음 명령어를 사용하십시오:

tmux attach -t opencode

세션, 대화 내용, 실행 중인 모든 작업은 이전 상태 그대로 유지됩니다. 이 상태는 연결이 끊겨도 유지되지만, 서버가 재부팅되면 유지되지 않습니다. 따라서 서버 재부팅 후에는 동일한 방식으로 새로운 tmux 세션을 시작해야 합니다.

모델 지정하기

OpenCode는 특정 제공업체에 종속되지 않습니다. AI SDK와 Models.dev 카탈로그를 사용하여 75개 이상의 제공업체를 지원합니다. 따라서 동일한 도구로 Anthropic, OpenAI, Google 및 로컬 서버를 포함한 수십 개의 제공업체를 사용할 수 있습니다. 가장 빠른 방법은 TUI 내부에서 /connect 명령어를 사용하는 것입니다. 이 명령어는 제공업체 목록을 표시하고 인증 정보를 처리합니다. 설정 내용을 커밋하고 재현하려면 프로젝트 루트에 opencode.json 파일을 생성하고 모델을 provider/model-id로 설정하십시오.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

OpenAI 호환 서버는 모두 제공업체로 선언할 수 있으므로 로컬 모델도 동일한 파일을 통해 작동합니다. 동일한 VPS에서 Ollama를 사용하여 모델을 서비스하는 경우, 설정이 해당 로컬 API를 가리키게 됩니다. 모델 이름은 ollama list가 시스템에 표시하는 이름과 동일해야 합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

첫날부터 적용할 만한 유용한 습관이 있습니다. OpenCode는 Tab 키로 전환 가능한 두 가지 agent를 제공합니다. 기본 agent인 Build는 모든 권한을 가지며, Plan은 변경 기능을 비활성화합니다. Plan 모드에서 새 작업을 시작하여 코드를 읽고 접근 방식을 제안하게 하십시오. 계획이 확정된 경우에만 Build 모드로 전환하십시오. 서버 환경에서 읽기 전용으로 먼저 검토하는 것은 안전한 방법입니다.

blast radius의 실체

Coding agent는 수동적이지 않습니다. 따라서 이 설정의 포함 범위와 한계를 명확히 설명합니다. 파일 손상 위험은 포함됩니다. opencode 사용자는 자신의 home 디렉터리만 소유하며 그 외에는 권한이 없습니다. 따라서 수정 및 삭제 작업은 해당 경계 내에서만 제한됩니다. 자격 증명 노출 위험도 포함됩니다. key는 mode 600 설정이 된 단일 파일에 하나의 계정으로 저장됩니다. 계정이 정당하게 수행할 수 있는 권한은 포함되지 않습니다. 만약 project directory에 production deploy 자격 증명이 있다면 agent가 이를 사용할 수 있습니다. 해당 자격 증명들을 agent 계정에서 완전히 분리하십시오.

OpenClaw와 같은 gateway agent와 달리, OpenCode는 daemon이 아닌 interactive terminal 프로그램입니다. listening port를 열지 않으며 long-running service도 실행하지 않습니다. 따라서 작성해야 할 systemd unit이나 agent 자체를 위해 방화벽을 설정할 port가 없습니다. 격리 범위는 user account와 project directory입니다. 이것이 이 가이드의 첫 번째 섹션이 가장 중요한 이유입니다.

하지만 격리된 환경이라도 표준 보안 관리가 필요합니다. coding VPS는 여전히 public server이기 때문입니다. SSH hardening on a VPS에서 설명하듯 root login을 비활성화한 key-only SSH를 사용하고, default-deny firewall을 설정하며, 정기적인 업데이트를 수행하십시오. 또한 agent가 생성한 결과물을 검토하십시오. 새로운 기여자의 pull request를 검토하는 것과 동일하게, push하기 전에 diff를 확인하십시오. 최종 배포는 사용자가 직접 수행하기 때문입니다.

마지막으로, 도구 자체를 최신 상태로 유지하십시오. OpenCode는 자주 릴리스되며, 업데이트에는 서버에서 명령어를 실행하는 프로그램에 필수적인 수정 사항이 포함됩니다. 업데이트 방법은 설치 시와 동일합니다. opencode 사용자로 install script를 다시 실행하거나, npm으로 설치했다면 sudo npm update -g opencode-ai를 실행한 후 opencode --version로 새 버전을 확인하십시오. 주기적인 짧은 유지보수가 몇 달 전 빌드에서 이미 해결된 버그를 디버깅하는 것보다 비용이 적게 듭니다.

FAQ

유료 API 대신 로컬 모델을 OpenCode에서 사용할 수 있습니까?

사용 가능합니다. OpenCode는 모든 OpenAI 호환 서버를 제공자로 취급합니다. 따라서 동일한 VPS에서 Ollama로 실행 중인 모델을 사용할 수 있습니다. opencode.json에 로컬 baseURL와 Ollama가 보고하는 모델 이름을 제공자로 선언하십시오. 주의할 점은 하드웨어 사양입니다. 실제 코딩 작업에 적합한 모델은 많은 메모리를 필요로 합니다. 모델을 다운로드하기 전에 서버 사양을 확인하십시오.

노트북을 닫은 후에도 OpenCode를 계속 실행하려면 어떻게 합니까?

VPS 내의 tmux에서 실행하십시오. tmux new -s opencode를 사용하여 이름이 지정된 세션에서 에이전트를 시작합니다. Ctrl-b를 누른 후 d를 눌러 세션을 분리(detach)하면 SSH 연결이 종료된 후에도 서버에서 세션이 계속 실행됩니다. tmux attach -t opencode를 사용하여 언제든 다시 연결(reattach)할 수 있으며, 대화 내용과 실행 중인 작업이 그대로 유지됩니다. 서버를 재부팅하면 세션이 종료되므로, 재부팅 후에는 새 세션을 시작하십시오.

OpenCode가 VPS에서 명령어를 실행하도록 허용해도 안전합니까?

제한된 권한을 부여하면 관리 가능합니다. OpenCode에 sudo 권한이 없는 전용 일반 사용자 계정을 부여하십시오. 모든 수정 사항을 되돌릴 수 있도록 프로젝트를 git으로 관리하십시오. API 키는 mode 600인 파일에 저장하십시오. Build agent가 변경을 수행하기 전에 Plan agent를 사용하여 먼저 읽기 전용으로 검토하십시오. 이렇게 하면 에이전트는 해당 계정이 소유한 파일만 손상시킬 수 있으며, 서버의 나머지 부분은 보호됩니다.

OpenCode와 Claude Code의 차이점은 무엇입니까?

OpenCode는 오픈 소스(MIT)이며 제공자에 종속되지 않습니다. 하나의 인터페이스를 통해 로컬 모델을 포함하여 75개 이상의 모델 제공자에 연결할 수 있습니다. Claude Code는 Anthropic 모델을 기반으로 구축된 Anthropic의 터미널 에이전트입니다. 다양한 제공자를 하나의 도구로 사용하거나 로컬 모델을 포함한 완전한 셀프 호스팅 스택을 원한다면 OpenCode가 적합합니다. 두 도구 모두 VPS 내 tmux에서 동일한 일반 사용자 설정으로 원활하게 실행됩니다.