SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Rakazo 셀프 호스팅: VPS 구축 및 서버 설정 가이드

Node 22, pnpm, Postgres, Graphile Worker를 활용한 Rakazo 셀프 호스팅 방법을 설명합니다. Docker Compose 환경 구성부터 샌드박스 컨테이너 관리, 그리고 봇 운영에 필요한 최소 VPS 사양과 메모리 최적화 전략을 상세히 안내합니다.

실제로 실행되는 self-hosting Rakazo 구성

self-hosting Rakazo는 하나의 Linux 서버에서 5가지를 실행한다는 뜻이다. PostgreSQL, Graphile Worker 프로세스, API, 웹 앱, 그리고 봇의 컴퓨터 역할을 하는 sandbox 컨테이너다. Rakazo는 elie222가 Apache 2.0 licence로 공개한 오픈 소스 Grok Bot 대안이다. 각 봇에는 고유한 대화, 메모리, 루틴, 기록이 있다. 별도의 Private Computer가 할당되지 않은 경우에는 워크스페이스의 다른 봇과 하나의 Team Computer를 공유한다. 또한 동료 봇이나 수명이 짧은 subagent를 생성할 수 있다. 이 문장에서 memory, subagent, tool call이 익숙하지 않다면, 먼저 에이전트가 실제로 작동하는 과정을 단계적으로 살펴보기를 반나절 정도 진행하는 것이 좋다. 아래 설정 대부분은 봇이 깨어났을 때 무엇을 하는지 그려볼 수 있어야 이해할 수 있기 때문이다.

마지막 부분 때문에 이 구성은 데스크톱이 아니라 VPS(virtual private server)에서 운영해야 한다. 메모리를 보유하고 예약 작업을 실행하는 봇은 사용자가 잠든 동안에도 접근할 수 있어야 한다. 절전 상태에 들어간 노트북에서는 큐 처리가 중단된다.

Rakazo는 2026년 10월 현재도 스스로 beta라고 설명한다. 현재 안정 버전 번호가 붙은 releases를 게시하고 있지만, 완성된 appliance가 아니라 실제 운영 중인 구성으로 다뤄야 한다. 전체 stack은 TypeScript로 작성되었다. 웹 앱에는 React 19와 Vite를 사용하고, API에는 Hono를 사용하며, 데이터베이스에는 Prisma를 사용하는 Postgres를 사용한다. 계정에는 Better Auth를 사용하고, background jobs에는 Graphile Worker를 사용한다. Graphile Worker는 Postgres 안에 큐를 저장하므로 Redis가 필요하지 않으며 실행할 두 번째 데이터 저장소도 없다. .env.example는 WAKEUP_DRIVER=graphile을 설정하며, 이는 봇이 깨어나는 작업이 Postgres를 기반으로 실행된다는 뜻이다. Postgres를 중지하면 예약된 모든 봇 작업도 함께 중지된다. 다른 제품을 실행하는 대신 구성 요소를 조합해 에이전트를 직접 만들고 싶다면 구성 요소로 직접 에이전트 만들기가 다른 선택지다.

1 GB 플랜으로는 부족한 이유

프로세스 수를 세어 보십시오. Postgres가 하나입니다. API는 Node 프로세스입니다. worker가 두 번째 프로세스입니다. web app이 세 번째입니다. sandbox supervisor가 네 번째입니다. 그 다음에는 봇이 사용하는 컴퓨터가 있습니다. 기본값은 그래픽 Linux 데스크톱을 포함하는 하나의 공유 Team Computer container이며, 활성 상태인 각 봇마다 별도의 X display와 Chrome 프로세스가 실행됩니다.

프로젝트의 self-host 문서에는 더 이상 호스트 크기가 제시되어 있지 않습니다. 2026년 10월 27일에 확인한 v0.3.5 문서에는 소프트웨어 요구 사항만 나와 있습니다. 대신 컴퓨터별 한도는 제시합니다. Docker sandboxes를 사용할 때 RAKAZO_COMPUTER_MEMORY의 기본값은 2g이고, RAKAZO_COMPUTER_CPUS의 기본값은 2입니다. 이 한도는 봇별 한도가 아니라 컴퓨터별 한도입니다. 각 workspace에는 기본적으로 하나의 Team Computer가 할당되고, 활성 상태인 모든 Team bot은 그 안에서 데스크톱과 브라우저를 실행하므로 2 GB와 2 cores를 함께 사용합니다. Private Computer로 이동한 봇만 자체 container와 자체 한도를 갖습니다. SANDBOX_PROVIDER=docker을 설정하면 이러한 데스크톱이 control plane 위에서 추가로 VPS에서 실행되므로, 4 GB는 목표값이 아니라 최소값입니다. 봇을 1개보다 많이 계속 실행할 계획이라면 8 GB부터 시작하십시오. 공유 컴퓨터가 해당 메모리를 실제로 사용할 수 있도록 RAKAZO_COMPUTER_MEMORY을 늘리고, 봇이 작업하는 동안 docker stats으로 실제 사용량을 측정하십시오. 메모리 사용량을 좌우하는 것은 sandbox 내부의 브라우저이므로 사양표만으로는 알 수 없습니다. 작은 장비에서 브라우저가 동시에 너무 많이 실행되지 않게 하려면 양수인 SANDBOX_TEAM_SCREEN_LIMIT을 설정하십시오. 이 값은 Docker Team Computer에서 활성 데스크톱 수를 제한합니다. 제공되는 0은 제한을 두지 않습니다. 전체 메모리가 부족하다면 RAKAZO_COMPUTER_MEMORY에 1536m와 같은 더 작은 값도 지정할 수 있습니다. agent 작업을 위해 장비 크기를 정하는 일반적인 방법은 agent VPS에 실제로 필요한 RAM과 CPU 용량에서 측정 방법을 자세히 설명합니다.

한 가지 설정으로 이 문제가 더 커지는 것을 막을 수 있습니다. .env.example은 SANDBOX_IDLE_MS=600000를 제공하며, 주석에는 해당 시간만큼 밀리초 단위로 유휴 상태가 지속되면 컴퓨터가 일시 중지되거나 중지된다고 적혀 있습니다. 10분 동안 유휴 상태이면 컴퓨터가 사라집니다. 허용되는 최소값은 30000이고, 0은 유휴 절전을 비활성화합니다. 같은 주석에서는 Docker self-host에서 0을 사용하도록 권장합니다. 유휴 컴퓨터에는 비용이 들지 않으므로 장시간 실행되는 앱과 세션을 계속 유지할 수 있기 때문입니다. 이는 비용에는 해당하지만 메모리에는 해당하지 않습니다. 소형 VPS에서는 타이머를 활성화해 두십시오. 타이머가 없으면 지금까지 시작한 모든 컴퓨터와 그 안의 모든 브라우저가 계속 실행됩니다.

디스크 사용량도 고려해야 합니다. sandbox image, Node modules, Postgres volume이 하나의 디스크를 함께 사용하므로 40 GB부터 시작하는 것이 합리적입니다.

복제 전 버전 고정

Rakazo는 빠르게 변화하며 main는 정식 릴리스가 아닙니다. 2026년 11월 9일 기준으로 2026년 11월 4일에 게시된 v0.8.0가 Latest로 표시된 릴리스입니다. 이 가이드는 2026년 10월 25일에 게시된 v0.3.5 버전을 기준으로 작성되었습니다.

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'

해당 커밋은 v0.3.5가 가리키는 지점입니다. 브랜치나 태그 대신 커밋을 고정하십시오. 브랜치는 다음 git pull 시점에 변경될 수 있고, 태그는 관리자가 다시 지정할 수 있는 이동식 라벨이므로 둘 다 되돌아갈 수 있는 특정 시점을 보장하지 않습니다. 커밋 식별자는 변경되지 않습니다. 업그레이드 후 문제가 발생했을 때 저렴한 해결책은 git checkout <old commit>를 수행하고 재빌드하는 것이며, 이는 정상 작동하던 커밋을 알고 있을 때만 가능하므로 서버 정보와 함께 커밋 ID를 기록해 두십시오. 고정된 README에서 Rakazo를 베타 버전으로 명시하고 있으므로, 이처럼 정확하게 버전을 고정하는 것은 작은 노력으로 큰 이득을 줍니다. 정식 릴리스 기록이 긴 프로젝트는 게시된 태그를 고정해도 되며, 이는 openGym과 같은 소규모 자체 호스팅 스택이 사용하는 방식입니다.

요구 사항: Node 22, pnpm 9 및 Docker

node -v
pnpm -v
docker --version

package.json은 "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" }와 "packageManager": "pnpm@9.15.0"을 명시합니다. 따라서 node -v는 v22.22.2 이상의 22.x 버전, 임의의 v24, 또는 v26 이상의 버전을 출력해야 합니다. v22이 22.22.2보다 낮으면 해당 범위에서 벗어나며, README에는 Node.js 23.x 및 25.x가 지원되지 않는다고 명시되어 있습니다. NodeSource나 nvm을 사용하여 지원되는 Node 버전을 설치하십시오. Corepack은 Node 22 및 24에 포함되어 제공됩니다. Node 26 이상에서는 npm install -g corepack를 사용하여 먼저 설치해야 합니다. 그 후 pnpm을 활성화하십시오:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine과 compose 플러그인이 나머지 요구 사항을 충족합니다. 셀프 호스팅 문서에서는 봇 홈 볼륨 하위 경로를 위해 Docker Engine 26 이상, API 1.45 이상과 함께 curl 및 OpenSSL을 요구합니다. 또한 사용자는 데몬에 접근할 수 있어야 합니다. docker ps이 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock을 반환한다면, 사용자를 docker 그룹에 추가하고 새로운 로그인 셸을 여십시오. 이 권한이 무엇을 의미하는지 먼저 파악하십시오. docker 그룹 멤버십은 해당 시스템의 root 권한과 동일합니다. 해당 그룹에 속한 사용자는 호스트 파일 시스템을 마운트하는 컨테이너를 시작할 수 있기 때문입니다.

.env 설정 및 Postgres 시작

cp .env.example .env
chmod 600 .env

서비스를 시작하기 전에 몇 가지 값을 변경해야 합니다. .env.example는 BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret 및 SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token을 포함하며, POSTGRES_PASSWORD와 POSTGRES_APP_PASSWORD은 비어 있습니다. 이러한 플레이스홀더는 저장소에 공개되어 있으므로, 그대로 배포하면 누구나 읽을 수 있는 보안 설정으로 운영하게 됩니다. 각 항목에 고유한 임의의 값을 부여하십시오. ENCRYPTION_KEY은 64자 길이의 임의 16진수 문자열이어야 하며, 이는 openssl rand -hex 32 명령어로 생성할 수 있습니다. 다른 보안 값은 32자 이상이어야 하므로, 각 항목에 대해 base64 명령어를 한 번씩 실행하십시오. Postgres 비밀번호 두 개는 URL 안전(URL-safe) 값이 필요하며, 마지막 줄의 명령어로 생성할 수 있으므로 각 비밀번호마다 실행하십시오. 데이터베이스에는 두 개의 로그인 계정이 있습니다. DATABASE_MIGRATION_URL은 마이그레이션을 수행하는 소유자 계정인 postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo로 제공되며, DATABASE_URL는 슈퍼유저 권한이 없고 행 수준 보안(row-level security)이 적용된 애플리케이션 전용 로그인 계정인 postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo으로 제공됩니다. 각 비밀번호를 해당 URL에 입력하십시오. pnpm db:migrate은 설정한 비밀번호로 rakazo_app 로그인을 생성합니다.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

그런 다음 데이터베이스를 단독으로 실행하고 마이그레이션을 수행하십시오.

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build는 package.json에 docker build -t rakazo/computer:local infra/sandboxes/computer로 정의된 봇 컴퓨터 이미지를 빌드합니다. 그래픽 이미지이므로 첫 빌드 시 많은 데이터를 내려받으며 시간이 소요됩니다. docker image ls rakazo/computer 명령어로 이미지가 생성되었는지 확인하십시오. 한 행이 출력되어야 합니다.

기본 compose 파일은 Postgres 포트를 외부에 노출하지 않습니다. 해당 명령어의 docker-compose.postgres-host.yml 오버레이는 포트를 127.0.0.1:5433로 노출하며, 이는 루프백(loopback) 전용이므로 pnpm db:migrate나 pnpm dev 같은 호스트 측 도구에서만 접근할 수 있습니다. 이 설정을 유지하십시오. Compose는 .env에 POSTGRES_PASSWORD이 없으면 Postgres를 시작하지 않지만, 인터넷에서 접근 가능한 Postgres 포트는 비밀번호 공격의 대상이 됩니다. 프로덕션 compose 파일은 동일한 변수를 읽으며 데이터베이스 포트를 노출하지 않습니다.

첫 실행

pnpm dev

이 명령은 API(포트 3100), Graphile Worker, Vite 웹 앱(포트 5173), 샌드박스 슈퍼바이저(포트 7091) 등 네 가지를 기본적으로 시작합니다. 해당 포트가 사용 중이면 pnpm dev가 다른 사용 가능한 포트 블록을 선택하고 URL을 출력합니다. 기본 포트 사용 시 앱은 http://127.0.0.1:5173에서 접속할 수 있으며, 로그인 페이지가 나타나야 합니다.

VPS를 사용하는 경우 해당 머신 앞에 직접 앉아 있는 것이 아니므로 5173 포트를 외부로 공개해서는 안 됩니다. 대신 자신의 머신에서 SSH(secure shell)를 통해 포트 포워딩을 수행하십시오.

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

이 소프트웨어를 실행하는 방식 간의 차이를 주의하십시오. pnpm dev은 Vite를 호스트에서 로컬로 바인딩하여 실행합니다. 개발용 compose 파일의 web 서비스는 127.0.0.1:5173:5173을, api 서비스는 127.0.0.1:3100:3100를 각각 로컬 루프백으로만 공개하므로 동일한 터널링 방식을 사용할 수 있습니다. 프로덕션 파일에서는 웹 앱이 호스트 포트를 공개하지 않고 자체 네트워크 내의 컨테이너에만 5173 포트를 노출하며, Caddy만이 80번과 443번 포트를 공개합니다. 따라서 운영 환경에서는 프로덕션 파일과 리버스 프록시를 사용하십시오.

서버에서 안전한 sandbox provider는 무엇인가?

이 설정은 반드시 올바르게 지정해야 한다. SANDBOX_PROVIDER의 .env는 기본적으로 docker이며, 고정된 checkout은 self-host 문서에 나열된 provider와 함께 Railway도 지원한다.

  • docker은 기본값이다. Bot computer는 사용자의 시스템에서 container로 실행된다. pnpm sandbox:build이 생성하고 supervisor가 실행하는 image를 기반으로 한다. 기본적으로 한 workspace의 bot은 하나의 Team Computer를 공유한다. Private Computer에서만 bot마다 자체 container가 제공된다. E2B account는 필요하지 않다.
  • e2b는 E2B에서 bot computer를 실행하며 E2B_API_KEY이 필요하다. v0.3.5에서는 key를 제공하면 production에서 이를 허용하며, NODE_ENV 제한이 없다. self-host 문서에서는 이를 public 또는 multi-user production에 적합하다고 설명한다. API와 database를 실행하는 host에서 bot computer를 분리할 수 있기 때문이다.
  • daytona, createos 및 boat은 추가적인 remote provider이다. 각각 자체 key인 DAYTONA_API_KEY, CREATEOS_SANDBOX_API_KEY 또는 BOAT_API_KEY이 필요하다.
  • railway는 Railway에서 computer를 실행하며 API와 worker에서 RAILWAY_API_TOKEN 및 명시적으로 선택한 RAILWAY_ENVIRONMENT_ID가 필요하다. sandbox에는 전용 Railway project 또는 environment를 사용한다.
  • desktop는 문서의 표현대로 API와 worker host에서 bot의 command를 직접 실행한다. v0.3.5에서는 NODE_ENV이 development 또는 test인 경우가 아니면 API와 worker가 이를 거부한다. 그러나 .env.example은 NODE_ENV=development을 ship하므로 pnpm dev를 실행하는 server에서는 여전히 이를 허용한다. public 또는 shared service에서는 활성화하지 않는다.
  • fake은 검증 전용 emulator다. runtime이 아니다.
  • none는 computer host 없이 product를 시작한다.

이 내용을 문자 그대로 받아들여야 한다. desktop mode에서는 isolation boundary가 전혀 없다. 따라서 bot은 API process를 실행하는 user의 권한으로 shell command를 실행하며, 해당 user의 home directory, SSH key, cloud credential 및 .env를 사용한다. bot이 읽는 web page의 text가 server에서 실행되는 command가 된다. server에서 desktop mode를 사용하면 bot이 credential을 보유하게 된다. 직접 사용하는 machine에서만 사용하거나, 아예 사용하지 않는다. provider를 전환하면 해당 web page 경로 주위에 container를 배치할 뿐 경로를 차단하지는 않는다. bot에 자체 SearXNG search backend 제공을 사용하면 search 측에서 발생하는 동일한 injection surface도 다룰 수 있다.

docker은 bot과 host 사이에서는 실제 boundary지만, bot 간에는 약한 boundary다. 기본적으로 bot은 하나의 Team Computer를 공유한다. computer runtime 문서에 따르면 Team bot은 OS user, workspace, browser profile, shell 및 X11 access를 공유한다. 또한 bot별 folder는 작업을 정리할 뿐 security boundary가 아니다. 따라서 어떤 Team bot이든 다른 Team bot의 file을 읽을 수 있다. 자체적인 격리가 필요한 bot은 Private Computer에서 실행해야 한다. docker provider는 이를 자체 network를 사용하는 별도의 sibling container로 실행한다. 그러나 해당 container를 생성하는 supervisor는 /var/run/docker.sock을 mount한다. self-host 문서는 이를 명확히 설명한다. 해당 socket에 접근할 수 있으면 Docker host를 제어할 수 있다. 따라서 supervisor는 private으로 유지해야 한다. .env.example은 SANDBOX_SUPERVISOR_TOKEN을 전용 credential로 취급하며, BETTER_AUTH_SECRET과 구분한다. Docker sandbox는 local development 외부에서 이를 필요로 한다. 또한 GitHub에서 누구나 읽을 수 있는 placeholder와 함께 제공된다. 자체적인 random value를 지정한다. 여기에서 가능한 가장 강력한 분리를 원한다면 e2b을 사용하거나, 다른 어떤 것도 보유하지 않은 machine을 Rakazo에 제공한다. 이것이 coding agent를 일회용 VM에서 실행하는 것과 같은 이유다. agent가 잘못된 작업을 수행해도 견디는 가장 저렴한 방법은 해당 machine의 가치가 없는 것이다.

모델 API 키는 어디에 설정합니까?

Rakazo의 선택적 모델 크레딧 결제 기능은 두 가지 Stripe 비밀값이 모두 설정되지 않으면 비활성화 상태로 유지됩니다. 사용자가 직접 키를 제공해야 합니다. .env.example은 PI_DEFAULT_PROVIDER=openrouter를 설정하므로, OPENROUTER_API_KEY이 일반적인 설정 위치이며 제공업체 키도 동일한 설정을 통해 작동합니다.

키는 .env에 보관하고 git에 커밋하는 파일에는 포함하지 마십시오. 저장소의 두 compose 명령어는 모두 --env-file .env를 전달하므로, git이 추적하는 YAML 파일에 값을 기록하지 않고도 컨테이너에 값을 전달할 수 있습니다. 또한 OPENROUTER_API_KEY을 비워두고 가입 후 앱에서 모델을 연결할 수도 있습니다. 이것이 바로 ENCRYPTION_KEY에 기본 제공되는 자리 표시자 대신 실제 무작위 값을 설정해야 하는 또 다른 이유입니다.

봇이 키를 사용하기 전에 제공업체 측에서 해당 키에 대한 지출 한도를 설정하십시오. 루프에 빠진 봇은 곧 비용을 발생시키는 봇입니다. Rakazo는 MAX_TOOL_CALLS_PER_TURN도 제공합니다. 양의 정수를 설정하면 도구 호출 예산을 초과하는 턴을 소프트 스톱(soft-stop) 처리하면서도 최종 어시스턴트 메시지를 생성할 수 있습니다. 설정하지 않거나 비워두거나 0으로 두면 제한 없이 작동합니다. 이는 금액이 아닌 도구 호출 횟수를 기준으로 하므로 제공업체의 지출 한도를 대체하지 않습니다. 이 키에는 고유한 이름을 지정하여 나중에 해당 키만 단독으로 취소할 수 있도록 하십시오. 본인이 아닌 팀을 위해 설정하는 경우, 모든 에이전트 앞의 OneCLI 단일 게이트웨이가 동일한 문제에 대한 다른 해결책이 될 수 있습니다. 이 방식은 제공업체 키를 개인별로 관리하지 않고 한곳에서 통합 관리하기 때문입니다.

개발 모드에서 상시 운영 환경으로 전환하기

이 저장소는 Postgres, API, 워커, 웹 앱, 그리고 자동으로 TLS(전송 계층 보안) 인증서를 발급받는 Caddy를 실행하는 프로덕션용 compose 파일을 제공합니다. 이 구성에서 포트를 외부에 노출하는 서비스는 Caddy뿐입니다. 봇 컴퓨터의 경우 기본값으로 E2B를 사용합니다. 선택 사항인 오버레이 infra/compose/docker-compose.prod.docker.yml을 사용하면 동일한 스택에서 로컬 Docker 컴퓨터를 실행할 수 있지만, 이 오버레이가 추가하는 슈퍼바이저는 호스트에서 root 권한과 동일한 수준의 권한을 갖게 된다는 점을 문서에서 경고하고 있습니다.

sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

스크립트를 실행하기 전에 키 전용 deploy 계정을 생성하고 해당 계정으로 로그인할 수 있는지 확인하십시오. harden-host.sh는 SSH 비밀번호 로그인과 root 로그인을 비활성화하고, SSH 속도 제한을 설정하며, 기존 사설 네트워크 규칙을 유지하면서 UFW(uncomplicated firewall)를 통해 SSH, HTTP, HTTPS 허용 규칙을 추가합니다. 또한 fail2ban, 자동 보안 업데이트, AppArmor 및 감사 규칙을 활성화합니다. 이 스크립트는 SSH_CONNECTION 없이는 실행되지 않으므로 명령 실행 시 sudo을 통해 전달해야 합니다. 또한 3분 이내에 새로운 SSH 세션에서 확인하지 않으면 방화벽 변경 사항을 되돌립니다. 이 스크립트는 로그인 방식과 SSH 설정을 변경하므로 실행 전 내용을 반드시 읽어보십시오. 새로운 SSH 로그인이 성공할 때까지 제공업체의 콘솔 창을 열어두십시오.

프로덕션용 .env는 개발용보다 더 많은 설정이 필요합니다. 셀프 호스팅 문서는 최소 요구 사항과 비밀 정보를 나열하고 있습니다.

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

첫 up을 실행하기 전에 도메인의 A 레코드가 서버를 가리키도록 설정하십시오. Caddy는 RAKAZO_HOST에 명시된 이름으로 인증서를 요청합니다. 해당 도메인 이름은 이 서버로 연결되어야 하며, HTTP 검증을 위한 80번 포트나 TLS-ALPN 검증을 위한 443번 포트 중 하나가 외부에서 접근 가능해야 합니다. 두 가지 검증 방식이 기본적으로 활성화되어 있으므로 80번 포트를 닫더라도 443번 포트를 통해 인증서가 발급되는 것을 막지는 못합니다.

처음부터 SIGNUP_ALLOWLIST를 본인의 주소로 설정하십시오. .env.example은 SIGNUPS_ENABLED=true을 포함하며, 두 설정 모두 API가 시작될 때마다 환경 변수에서 읽어옵니다. 따라서 가입 기능이 켜져 있고 허용 목록(allowlist)이 없는 상태로 공개 도메인에 인스턴스를 배포하면, 누구나 해당 서비스를 찾아 가입할 수 있습니다. 비어 있지 않은 허용 목록은 시작 시마다 적용되며 기존에 저장된 목록을 대체합니다. 허용 목록을 통한 가입은 메일함 인증을 요구하며, 첫 번째 계정도 이에 포함되므로 가입 전에 이메일 발송 설정을 완료하십시오. 이메일 설정이 없다면 문서에서 안내하는 대로 SIGNUPS_ENABLED=false로 시작하여 서버 측 부트스트랩 명령을 통해 계정을 생성해야 합니다. 이 방식은 서버 권한이 없는 일반적인 인증 계정을 생성합니다. 먼저 허용 목록을 설정하고, 필요하다면 나중에 완화하십시오. 이미 동일한 서버에서 여러 서비스를 운영 중이며 서비스별 허용 목록 대신 통합된 사용자 관리 체계를 원한다면, Authentik 인스턴스를 앞단에 배치하여 프록시에서 접근 제어를 수행할 수 있습니다. 단, 이 방식은 Rakazo의 자체 Better Auth 계정을 대체하는 것이 아니라 그 앞단에 위치하게 됩니다.

저장소 내의 docs/self-host.md를 프로덕션 설정의 기준으로 삼으십시오. 코드가 변경됨에 따라 이 파일도 함께 변경되지만 본 가이드는 실시간으로 업데이트되지 않기 때문입니다. Compose가 작업을 수행하므로 일반적인 규칙이 적용되며, VPS를 위한 Docker Compose 기초 문서는 스택을 장기간 운영할 때 왜 --env-file과 명명된 볼륨(named volumes)이 중요한지 설명합니다.

백업

이 구성에서 Postgres와 data/ 디렉터리는 인스턴스의 데이터를 보관합니다. 복구 시에는 ENCRYPTION_KEY와 설정된 콘텐츠 마스터 키도 필요하므로, 서버 외부에도 사본을 보관하십시오.

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh은 Postgres를 덤프하고 data/를 아카이브합니다. restore.sh는 개발용 Compose 스택에서 애플리케이션 서비스를 중지한 상태로 빈 데이터베이스에 대해 작동하며, 운영 환경의 백업 파일을 읽지 않습니다. 운영 중인 서버의 경우, 저장소에서 제공하는 타이머를 사용하여 infra/compose/backup-prod.sh을 /usr/local/sbin/rakazo-backup로 설치하십시오. 이 도구는 검증된 덤프와 앱 데이터 아카이브를 /var/backups/rakazo에 기록합니다. 기본적으로 RAKAZO_BACKUP_KEEP에 설정된 대로 최대 3개의 검증된 스냅샷을 보관하며, RAKAZO_BACKUP_MAX_GB에 설정된 50 GiB 제한 내에서 관리합니다. 또한 매 실행 전 부분적인 스냅샷과 오래된 기록을 삭제하므로 별도의 작업 없이도 순환 백업이 이루어집니다. 각 백업은 /etc/rakazo/backup.env에 나열된 공개 수신자에게 age를 사용하여 암호화할 수 있으며, 이를 통해 서버는 자신이 읽을 수 없는 백업 파일을 생성하게 됩니다. 해당 키 쌍은 관리자가 제어하는 기기에서 생성하고 개인 키는 서버 외부에서 보관하십시오. 수신자가 없으면 백업은 평문으로 저장되고 경고 로그가 남지만, 첫 번째 암호화 백업 이후에는 RAKAZO_BACKUP_ALLOW_PLAINTEXT=1를 통해 평문 저장을 명시적으로 허용하지 않는 한 수신자 없이 실행 시 실패합니다. 데이터베이스와 동일한 디스크에 있는 백업은 진정한 백업이 아니므로, 반드시 서버 외부로 복사하십시오. 이후 실제 복구가 필요한 상황이 오기 전에 여분의 서버에서 한 번 복구를 시도해 보십시오.

실패 원인과 확인 방법

pnpm db:migrate이(가) 데이터베이스에 연결할 수 없습니다. 마이그레이션 과정에서 127.0.0.1:5433에 있는 데이터베이스 서버에 접근할 수 없다고 보고합니다. Postgres 컨테이너가 실행 중이 아니거나, 실행 중이지만 아직 준비되지 않았거나, 5433 포트를 호스트에 노출하는 docker-compose.postgres-host.yml 오버레이 없이 시작되었을 가능성이 있습니다. docker compose --env-file .env -f infra/compose/docker-compose.yml ps을(를) 실행하여 postgres 서비스가 정상(healthy) 상태인지 확인하십시오. compose 파일에는 3초마다 실행되는 상태 확인(health check) 설정이 포함되어 있습니다. 컨테이너가 재시작을 반복한다면 로그를 확인하십시오. 고정된 Compose 스택은 Postgres 18로 마이그레이션되기 전까지는 이전 Postgres 16 볼륨에서 시작되지 않습니다. docker compose ... down -v은(는) 이를 초기화하며, 이 과정에서 데이터도 함께 삭제됩니다.

포트가 이미 사용 중입니다. 다른 프로세스가 5433 포트를 점유하고 있으면 Postgres 실행이 bind: address already in use 오류와 함께 실패합니다. 보통 이전에 중지하지 않은 Rakazo 스택이 원인입니다. sudo ss -lntp | grep 5433을(를) 실행하면 해당 프로세스 이름을 확인할 수 있습니다. 오버레이는 POSTGRES_HOST_PORT에서 호스트 포트를 읽어오므로, DATABASE_URL 및 DATABASE_MIGRATION_URL을(를) 함께 수정한다면 포트를 변경할 수 있습니다.

봇이 컴퓨터를 할당받지 못합니다. SANDBOX_PROVIDER=docker이(가) 설정되어 있는데 rakazo/computer:local 이미지가 없다면 시작할 대상이 없습니다. docker image ls rakazo/computer은(는) 이 문제를 한 줄로 요약하며, pnpm sandbox:build으로(로) 해결할 수 있습니다. supervisor가 Docker 소켓에 접근할 수 없는 경우에도 컨테이너를 생성할 수 없으며, 이때 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock 경로가 포함된 메시지가 출력됩니다.

긴 명령어가 중간에 종료됩니다. .env.example은(는) SANDBOX_COMMAND_TIMEOUT_MS=300000을(를) 설정하므로, 봇 컴퓨터 내부의 단일 명령은 5분이 지나면 중단됩니다. 샌드박스가 충돌했다고 가정하기 전에 느린 빌드를 위해 이 값을 높이십시오.

pnpm install이(가) 알 수 없는 이유로 중단됩니다. 다른 무엇보다 먼저 node -v을(를) 확인하십시오. 워크스페이스는 ^22.22.2 || ^24.0.0 || >=26.0.0을(를) 선언하므로, 23.x, 25.x 및 22.22.2 이전의 모든 22.x 버전은 범위를 벗어납니다. 고정된 .npmrc은(는) engine-strict=true을(를) 설정하므로, pnpm install은(는) 애플리케이션 의존성 코드가 실행되기 전에 지원되지 않는 Node 버전을 engine/version 오류로 거부합니다.

로컬에서는 로그인이 되지만 도메인을 통하면 되지 않습니다. BETTER_AUTH_URL, WEB_ORIGIN, API_URL 모두 주소창에 입력된 것과 동일한 퍼블릭 오리진(스키마 포함)을 가지고 있어야 합니다. 세션이 유지되지 않는 가장 흔한 원인은 이들 중 하나에 남아 있는 오래된 http://127.0.0.1:5173 설정 때문입니다.

고정된 체크아웃 업데이트

체크아웃에서 빌드한 프로덕션 Compose 스택을 위한 셀프 호스팅 문서의 업그레이드 경로는 간단합니다. 새로운 소스를 pull한 다음, API, 워커, 웹 앱을 다시 빌드하고 재시작하면 됩니다. API는 시작 명령에서 마이그레이션을 먼저 적용한 뒤 서비스를 제공하므로, API가 시작될 때 마이그레이션이 실행됩니다.

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

먼저 백업을 수행하십시오. 마이그레이션은 앞으로만 진행되며, 베타 버전에서는 신뢰할 수 있는 되돌리기 경로를 제공하지 않습니다. 체크아웃 시점이 2026년 8월 30일 이전이고 v0.1.0-beta 커밋을 포함하고 있다면, 업그레이드 전에 문서의 20260830200000_space_scope_names_and_user_credentials 마이그레이션 관련 참고 사항을 읽어보십시오. 이는 조정된 전환 작업이므로, 기존 API와 워커를 먼저 중지하고 문서에서 제공하는 Space 개인정보 보호 경계 검사를 실행하십시오. 별도의 앱 로그인이 도입되기 이전의 체크아웃에서 업그레이드하는 경우, 재빌드 전에 .env에 POSTGRES_APP_PASSWORD를 설정해야 합니다. 이 설정이 없으면 프로덕션 compose 파일이 시작되지 않습니다. 소스 체크아웃 및 프로덕션 Compose 파일은 Postgres 18을 실행합니다. 기존 Postgres 16 설치 환경은 새로운 레이아웃에서 시작하기 전에 문서의 infra/compose/upgrade-postgres.sh 절차를 수행해야 합니다. 프로젝트가 초기 단계라 예고 없이 환경 변수 이름을 변경하는 경우가 있으므로, 업데이트를 적용하기 전에 고정된 SHA와 새로운 SHA 사이의 커밋 내용을 확인하십시오. 환경 변수가 누락되면 서비스가 시작되었다가 바로 종료되는 현상이 발생합니다. Rakazo가 운영하기에 적합한 도구인지 아직 결정 중이라면, 셀프 호스팅 AI 에이전트 요약에서 이 범주에 속하는 다른 도구들과 각각의 유지 비용을 확인할 수 있습니다.

FAQ

1 GB VPS에서 Rakazo를 실행할 수 있습니까?

아니요. Postgres, API, 워커, 샌드박스 슈퍼바이저, 웹 앱이 동시에 실행됩니다. 여기에 SANDBOX_PROVIDER=docker를 사용하면 봇의 컴퓨터는 그래픽 데스크톱을 포함하는 컨테이너를 추가하며, 활성화된 각 봇마다 별도의 X 디스플레이와 Chrome 프로세스가 생성됩니다. 이 모든 구성 요소는 기본적으로 2 GB 메모리와 2개의 CPU라는 제한 내에서 동작합니다. v0.3.5의 셀프 호스팅 문서에는 호스트 사양에 대한 언급이 없습니다. 컨트롤 플레인의 최소 사양으로 4 GB를 고려하고, 로컬 머신에서 데스크톱을 실행할 때는 더 높은 사양을 준비하십시오.

서버에서 데스크톱 샌드박스 제공자를 사용하는 것은 안전합니까?

아니요. 셀프 호스팅 문서에 따르면 desktop는 API 및 워커 호스트에서 명령을 직접 실행합니다. 따라서 봇은 해당 프로세스를 실행하는 사용자의 권한으로 동작하며, 해당 사용자의 파일과 자격 증명에 접근할 수 있습니다. v0.3.5에서 API와 워커는 개발 및 테스트 모드가 아닐 경우 이를 거부하지만, pnpm dev를 실행 중인 서버는 개발 모드이므로 이를 허용합니다. 공개 서버나 공유 서버에서는 사용하지 마십시오. 봇이 작업 공간의 다른 봇과 파일을 공유해서는 안 될 때는 docker를 사용하여 봇에게 Private Computer를 제공하거나, 여러 명이 로그인하는 환경이라면 e2b를 사용하십시오.

Rakazo의 어떤 버전을 설치해야 합니까?

2026년 11월 9일 기준으로 최신 릴리스는 2026년 11월 4일에 게시되어 Latest로 표시된 v0.8.0입니다. 이 가이드를 따르려면 main이나 8월의 v0.1.0-beta 프리릴리스를 추적하는 대신, 고정된 v0.3.5 커밋인 f31e3c0699f086d663637c4107858c238a086fb3를 체크아웃하십시오. 브랜치는 계속 변경될 수 있고 태그는 재지정될 수 있으므로, 두 방식 모두 특정 시점의 소스 코드를 보장하지 않습니다. 롤백은 정상 작동했던 버전을 알 때만 가능하므로 반드시 커밋 해시를 기록해 두십시오.

OpenRouter API 키는 어디에 입력합니까?

OPENROUTER_API_KEY으로 .env에 입력하며, 커밋하는 compose 파일에는 절대 포함하지 마십시오. 저장소의 두 compose 명령어 모두 --env-file .env를 전달하므로, 추적되는 YAML 파일에 값을 기록하지 않고도 컨테이너에 값을 전달할 수 있습니다. 값을 비워두고 가입 후 앱 내에서 모델을 연결할 수도 있습니다. 봇이 루프에 빠지면 멈출 때까지 모델을 계속 호출하므로, 제공자 측에서 키에 대한 사용 한도를 설정하십시오.

도메인 이름과 TLS가 필요합니까?

초기 테스트 단계를 넘어서는 모든 경우에 필요합니다. 프로덕션용 compose 파일은 Caddy를 실행하여 인증서를 자동으로 발급받습니다. RAKAZO_HOST를 공개 호스트명으로 설정하고, BETTER_AUTH_URL, WEB_ORIGIN, API_URL을 동일한 공개 HTTPS 오리진으로 설정하십시오. 처음 확인하는 단계라면 도메인 없이 진행할 수 있습니다. pnpm dev를 실행하고 포트 5173을 외부에 공개하는 대신 SSH를 통해 포트 포워딩하십시오.

이 글이 도움이 되었나요?