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

VPS에서 KiroCrew 직접 호스팅 및 상시 구동 방법

KiroCrew 게이트웨이를 VPS에서 Docker 컨테이너로 실행하여 예약 작업과 세션 데이터를 안정적으로 유지하는 방법을 설명합니다. systemd 설정부터 버전 롤백 전략까지, 항상 켜져 있는 에이전트 환경을 구축하기 위한 필수 가이드를 확인하십시오.

노트북 대신 VPS에서 KiroCrew를 직접 호스팅해야 하는 이유

KiroCrew를 직접 호스팅하는 것은 항상 켜져 있는 기기에서만 효과가 있으므로, 노트북이 아닌 VPS가 적합한 환경입니다. KiroCrew는 세션 기록, 의미론적 메모리, 예약된 작업, 승인 대기열을 디스크에 저장하며 프로세스가 재시작될 때 이 모든 데이터를 다시 불러옵니다. 예약된 작업이 실행되어야 할 03:00에 프로세스가 실행 중이지 않다면 아무런 소용이 없으며, 닫혀 있는 노트북은 이를 실행할 수 없습니다.

KiroCrew는 Kiro 팀에서 제공하는 오픈 소스 에이전트 워크스페이스로, Apache 2.0 라이선스를 따르며 0.1.0 버전이 2026년 7월 22일에 릴리스되었습니다. 게이트웨이라 불리는 단일 프로세스가 상태를 관리하며 5476 포트에서 웹 대시보드를 제공합니다. 이 게이트웨이에는 대시보드, kirocrew CLI, 또는 Slack과 같은 채팅 채널을 통해 접근할 수 있습니다. 직접 호스팅하는 대상은 게이트웨이뿐이므로, 이 가이드는 게이트웨이를 항상 실행 상태로 유지하고, 공용 인터넷으로부터 격리하며, 잘못된 업그레이드 이후 복구하는 방법에 초점을 맞춥니다.

시작하기 전에 알아두어야 할 두 가지 사항이 있습니다. 0.11.0 이후부터, 저장된 하네스(harness) 선택 사항이 없는 새로운 KiroCrew 설치는 kiro-cli 없이도 기본적으로 KAS를 사용합니다. 기존에 Kiro CLI에서 명시적으로 선택한 설정은 그대로 유지됩니다. Kiro 백엔드에서의 추론은 사용자의 Kiro 플랜을 사용하므로, 2026년 11월 1일 기준으로 이 기본 설정은 오프라인 상태가 아닙니다. 또한 이 프로젝트는 초기 단계이며 빠르게 변화합니다. 안정화 버전은 2026년 8월 5일 0.1.3에서 2026년 10월 25일 0.10.0로 업데이트되었으며, 그 사이 10월 9일에는 0.8.0, 10월 16일에는 0.9.0가 릴리스되었고, 10월 25일에는 이미 0.11.0 릴리스 후보가 프리릴리스로 공개되었습니다. 언제든 롤백이 필요할 수 있음을 가정하고, 롤백이 가능한 방식으로 설치하십시오. 서버에서 에이전트를 실행해 본 적이 없다면, VPS에서 코딩 에이전트 실행하기에서 이 가이드의 기반이 되는 기본 규칙을 확인하십시오. 서버 운영보다 에이전트 측면이 생소하다면, 먼저 에이전트 루프, 도구, 메모리의 실제 의미 이해하기를 읽어보는 것이 아래의 선택 사항들을 단순한 주문이 아닌 의사결정으로 이해하는 데 도움이 될 것입니다.

KiroCrew의 요구 사항과 상태 저장 위치

네이티브 설치 시 Python 3.12 이상이 필요하며, 대시보드를 소스에서 빌드할 경우 Node.js 22.12.0 이상이 필요합니다(프로젝트에서는 Node 24 LTS를 권장합니다). Kiro CLI 백엔드는 kiro-cli이 필요하며, kiro-cli login 또는 자동화 사용을 위한 API 키로 인증해야 합니다. 0.10.0 이후부터 내장 KAS 엔진은 kiro-cli 설치 없이 실행되며, 0.11.0부터는 저장된 하니스(harness) 설정이 없는 신규 설치 시 기본값으로 적용됩니다. 컨테이너 설치 시에는 호스트에 이러한 구성 요소가 필요하지 않습니다. 오직 Docker만 있으면 됩니다. 이것이 컨테이너 설치를 권장하는 주된 이유입니다.

상태는 ~/.kiro/crew에 저장되며, KIROCREW_HOME 환경 변수를 통해 위치를 변경할 수 있습니다. 해당 디렉터리 내부 구성은 다음과 같습니다.

  • config.json: 게이트웨이 설정 및 채팅 채널 자격 증명.
  • .env: 보안 비밀(secrets).
  • workspace/memory/: 환경 설정, 프로젝트 노트 및 채팅 기록.
  • memory.db 및 memory_index.db: 의미론적(semantic) 인덱스 및 전문(full-text) 인덱스.
  • models/: 첫 실행 시 다운로드되는 임베딩 모델.
  • security_events.jsonl: 보안 이벤트 로그.

해당 디렉터리가 곧 설치 그 자체입니다. 이 디렉터리를 새 VPS로 복사하면 에이전트 이전이 완료되므로, 아래의 백업 섹션이 설치 섹션보다 더 중요합니다.

RAM보다는 디스크 용량을 고려하십시오. 게이트웨이는 Python 프로세스입니다. 실제로 시스템 부하를 일으키는 것은 에이전트가 실행하는 빌드나 테스트 스위트와 같은 작업입니다. 상태 디렉터리는 채팅 기록이 쌓이면서 커지며, 임베딩 모델은 첫 실행 시 생성됩니다. 따라서 프로젝트 초기 몇 달간 게시된 수치를 맹신하기보다는, 몇 주 사용 후 du -sh ~/.kiro/crew를 사용하여 본인의 환경에서 직접 측정하십시오. 모든 작업자에게 개별 컨테이너와 브라우저를 할당하는 런타임 환경과 비교했을 때, OpenBot의 AI 동료를 직접 호스팅하는 경우에는 디스크보다 RAM 용량 산정이 우선적인 문제가 됩니다.

네 가지 설치 경로 중 무엇을 사용해야 하는가

이 프로젝트는 데스크톱 앱, 한 줄짜리 wheel, 소스 코드, Docker 등 네 가지 설치 방식을 제공합니다. 한 줄짜리 설치 프로그램은 wheel을 가져와 kirocrew 런처를 생성합니다. 만약 해당 디렉터리가 PATH에 포함되어 있지 않으면, 이를 추가하라는 안내 메시지가 출력됩니다.

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

이 설치 프로그램은 채널 플래그와 버전 플래그를 인자로 받습니다.

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.8.0

컨테이너 이미지는 ghcr.io/kirodotdev/kirocrew에 게시되며, 모든 태그에서 linux/amd64 및 linux/arm64를 지원합니다. 소스 빌드는 git clone와 make build를 조합한 방식이며, 이는 코드를 수정하는 개발자를 위한 것이지 단순히 실행하려는 사용자를 위한 것이 아닙니다.

컨테이너를 사용하십시오. 네이티브 소스 설치 방식은 다른 서비스를 실행 중인 호스트에 Python 패키지와 Node를 함께 설치하게 되며, Kiro CLI 백엔드를 사용할 경우 kiro-cli까지 추가됩니다. 따라서 업그레이드 과정에서 문제가 발생하면 이를 수동으로 일일이 해결해야 합니다. 컨테이너는 런타임을 하나의 이미지로 유지하고 상태를 하나의 볼륨에 저장하므로, 롤백이 필요할 경우 태그를 변경하고 재시작하는 것만으로 충분합니다.

이미지를 stable 대신 릴리스 태그에 고정하십시오

프로젝트의 자체 예제는 stable 태그를 사용합니다:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable는 유동적인 태그이며, 동일한 릴리스를 가리키는 latest도 마찬가지입니다. 이 태그들은 항상 최신 안정 릴리스를 가리키므로, 다음 pull 시점에 사용자가 의도하지 않아도 실행 중인 버전이 변경될 수 있으며 태그에는 어떤 버전이 사용되었는지에 대한 기록이 남지 않습니다. 버전 태그는 불변하므로 특정 버전에 고정하십시오. 2026년 11월 1일 기준 최신 안정 릴리스는 2026년 10월 31일에 게시된 0.11.1이며, 이는 0.11.0의 메모리 무결성 및 KAS 수정 사항을 포함한 핫패치 버전입니다. 아래의 0.8.0 예제는 Kiro CLI를 사용합니다. insider 및 nightly 태그도 존재하며, nightly는 main에서 빌드된 버전을 추적합니다.

/opt/kirocrew/compose.yaml를 작성하십시오:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.8.0
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

서비스를 시작한 뒤, 이미지가 자체 HEALTHCHECK를 위해 사용하는 상태 확인 엔드포인트를 점검하십시오:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps은 1분 이내에 컨테이너가 정상 상태임을 보고해야 하며, /api/health은 토큰 없이 응답합니다(/api/live 및 /api/ready도 마찬가지이며, 이것이 프로브로 사용 가능한 이유입니다). 상태가 starting으로 유지된다면 설정을 변경하기 전에 docker logs kirocrew을 읽어보십시오. 첫 실행 시 백그라운드에서 임베딩 모델을 다운로드하며, 모델이 도착하기 전까지 메모리 검색은 키워드 매칭을 사용합니다.

systemd를 이용한 서비스 유지

restart: unless-stopped는 컨테이너가 충돌하거나 재부팅된 이후에도 Docker가 부팅 시 시작된다면 컨테이너를 다시 실행합니다. unit 파일을 사용하면 이러한 의존성을 명확히 할 수 있으며, 백업 전 전체 스택을 중지하는 명령어를 하나로 통합할 수 있습니다. Docker Compose 스택을 부팅 시 시작하기에서 일반적인 패턴을 다룹니다. KiroCrew의 구성 방식은 /etc/systemd/system/kirocrew.service에 나와 있습니다.

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew의 상태는 active (exited)이어야 하며, 이는 해당 unit의 정상적인 결과입니다. RemainAfterExit=yes을 사용한 Type=oneshot가 여기에 적합한 이유는 docker compose up -d이 컨테이너를 시작하자마자 반환되기 때문입니다. 즉, systemd는 포그라운드 프로세스가 아닌 스택이 실행 중이라는 사실을 추적합니다. 대신 Type=simple를 작성하면 systemd는 명령어가 즉시 종료된 것으로 간주하여 서비스를 dead 상태로 표시하고, Restart= 설정에 따라 포기하거나 재시작 루프에 빠지게 됩니다. 네이티브 설치의 경우 프로젝트에서 자체적으로 제공하는 kirocrew service install를 사용하며, 이는 /etc/systemd/system/kirocrew.service를 작성하고 사용자의 권한으로 게이트웨이를 실행합니다. 두 unit을 동시에 실행하지 마십시오. 이 주제에 대한 더 자세한 내용은 VPS에서의 systemd 서비스 및 타이머에서 확인할 수 있습니다. 다시 시작되지 않는 unit은 별도의 조치를 취하지 않으면 침묵을 지킵니다. 따라서 자신의 ntfy 서버로 알림을 보내는 OnFailure= 핸들러를 추가하십시오. 그러면 실행되지 않은 예약 작업 대신 휴대폰을 통해 게이트웨이가 다운되었음을 즉시 알 수 있습니다.

첫 실행: 로그인 및 대시보드 토큰 획득

컨테이너가 게이트웨이를 시작하지만, 고정된 0.8.0 이미지에 포함된 기본 Kiro CLI 런타임은 여전히 인증이 필요합니다. 컨테이너 내부에서 로그인하거나, 자동화된 사용을 위해 KIRO_API_KEY을 컨테이너 환경 변수로 전달하십시오:

docker exec -it kirocrew kiro-cli login

이 명령을 실행하면 기기 코드와 브라우저에서 열어야 할 URL이 출력됩니다. 그 후 대시보드 토큰을 생성하십시오:

docker exec kirocrew kirocrew token --ttl 2h

대시보드 URL은 http://localhost:5476/?token=<the token>입니다. 토큰에는 만료 시간이 있습니다. 출력된 링크는 생성 후 5분 이내에 열어야 하며, 이 명령은 2시간 동안 유효한 액세스 쿠키를 요청합니다. 문서화된 최대 시간은 20시간입니다. 브라우저는 30일의 슬라이딩 유휴 윈도우를 가진 갱신 쿠키도 함께 받으므로, 활성 세션은 별도의 링크 없이 자동으로 갱신됩니다. 대시보드가 빈 화면으로 로드되거나 즉시 튕겨 나간다면 토큰이 만료된 경우일 가능성이 높으므로, 새로 생성하여 즉시 여십시오. 토큰을 티켓이나 채팅 메시지에 붙여넣지 마십시오. 토큰을 가진 사람은 귀하의 에이전트를 제어할 수 있습니다.

SSH를 통해 대시보드에 접속하고 5476 포트는 절대 공개하지 마십시오

프로젝트 예제에 있는 바인드 주소 -p 127.0.0.1:5476:5476를 다시 확인하십시오. 컨테이너 내부에서 게이트웨이는 0.0.0.0에서 대기합니다. 포트 매핑을 통해 접근 가능해야 하기 때문이지만, 매핑 자체는 호스트의 루프백 주소로만 공개됩니다. 127.0.0.1: 접두사를 삭제하면 해당 포트를 스캔하는 누구에게나 게이트웨이가 공개 인터넷상에 노출됩니다. ufw 규칙도 여러분을 보호하지 못합니다. Docker는 ufw 규칙이 적용되기 전에 트래픽을 라우팅하는 DNAT 규칙을 작성하여 포트를 게시하므로, ufw deny 5476은 게시된 포트에 아무런 영향을 주지 못합니다. Docker의 기본 iptables 백엔드에서 Docker가 제공하는 해결책은 DOCKER-USER 체인에 필터링 규칙을 넣는 것입니다. 이 방법은 작동하지만, conntrack 확장 기능을 사용하여 매칭하지 않는 한 해당 규칙은 컨테이너의 내부 주소와 포트를 보게 됩니다. 따라서 루프백 바인딩을 유지하는 것이 더 간단하며 실수를 줄일 수 있는 방법입니다. Docker의 nftables 백엔드는 대신 사용자 정의 필터링을 위해 별도의 nftables 테이블과 기본 체인을 사용합니다. Docker 포트가 ufw를 우회하는 현상에서 해당 메커니즘을 자세히 다룹니다.

대신 노트북에서 SSH를 통해 포트를 포워딩하십시오:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

해당 프로세스를 실행 상태로 두고 로컬에서 http://localhost:5476/?token=<the token>을 여십시오. 연결할 때마다 자동으로 포워딩되도록 하려면 ~/.ssh/config에 다음 내용을 추가하십시오:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

노트북에서 5476 포트를 이미 사용 중이라면 왼쪽 숫자만 변경하십시오: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, 그런 다음 http://localhost:45476/?token=...으로 접속하십시오. 추가적인 루프백 포트 설정이나 컨테이너 재생성은 필요하지 않습니다. 루프백 Origin이 요청의 Host와 일치하므로 CSRF 검사가 통과됩니다. 두 번째 에이전트가 서버를 공유하게 되면 이와 같이 포워딩을 쌓게 될 것입니다. 보안 스캔을 위한 open-kritt 셀프 호스팅에서는 5173 포트에 또 다른 루프백 전용 대시보드를 동일한 서버에 배치하기 때문입니다.

대시보드에서 변경할 수 있는 설정은 두 가지 문서화된 동작에 의해 결정됩니다. 첫째, 게이트웨이는 포워딩 헤더(Forwarded, X-Forwarded-* 또는 X-Real-IP)가 포함된 모든 요청을 원격 요청으로 간주하며, 설정 쓰기 및 비밀 정보 노출 엔드포인트는 이러한 요청을 거부합니다. 리버스 프록시는 해당 헤더를 추가하지만, 일반적인 ssh -L 포워딩은 헤더를 추가하지 않으므로 로컬 요청으로 간주되어 거부되지 않습니다. 둘째, 컨테이너 이미지 내의 채널 자격 증명 페이지와 비밀 정보 노출 뷰는 직접적인 로컬 접속이 아닌 브라우저에 대해서는 읽기 전용으로 동작하며, 이미지에는 텍스트 편집기가 포함되어 있지 않습니다. 대시보드에서 채널 자격 증명이 저장되지 않는 것은 버그가 아니라 의도된 동작입니다. 대신 호스트에서 설정을 편집하십시오:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

휴대전화로 접속할 경우 프로젝트에서는 Tailscale의 tailscale serve을 권장합니다. 이는 대시보드를 공개 호스트명이 아닌 사용자의 tailnet 내부에 유지해 줍니다. 공개 리버스 프록시보다 이 방법을 선호하십시오. 토큰은 URL에 포함되어 전달되며, URL은 경로상의 모든 접근 로그에 기록됩니다. 이 규칙은 포트 자체가 아니라 포트 뒤에 무엇이 있는지에 관한 것입니다. Jellyfin 라이브러리를 90년대 비디오 가게처럼 재구성하는 Halcyon과 같이 다른 사람들이 열어볼 수 있도록 설계된 서비스는 리버스 프록시에 적합하지만, 서버에서 명령을 실행할 수 있는 게이트웨이는 그렇지 않습니다.

에이전트의 폭발 반경을 최소화하십시오

컨테이너는 처음 시작될 때 샌드박스 지원 여부를 확인하며, 그 결과에 따라 에이전트의 실행 가능 여부가 결정됩니다. 네임스페이스 격리가 가능하다면 에이전트의 하위 프로세스는 격리된 상태로 실행됩니다. 격리가 불가능한데 KIROCREW_ALLOW_UNSANDBOXED=1가 설정되지 않았다면, 보안이 적용되지 않은 상태로 실행되는 대신 실행 자체가 거부됩니다. 따라서 게이트웨이는 정상으로 보이지만 모든 작업이 멈춰 있다면 대개 이 문제입니다. 이 결정은 첫 실행 시 docker logs kirocrew에 기록됩니다. 프로젝트는 적용 가능한 seccomp (secure computing mode) 프로필도 제공합니다.

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json
    security_opt:
      - seccomp:./kirocrew-seccomp.json

AppArmor가 활성화된 호스트에서 프로젝트의 Docker 가이드는 seccomp 프로필만으로는 절반의 조치에 불과하다고 설명합니다. Docker는 자체적인 docker-default AppArmor 프로필을 연결하고 이를 apparmor=unconfined와 결합하기 때문입니다. 이 옵션은 AppArmor의 컨테이너별 규칙만 해제할 뿐, seccomp 프로필, 제거된 권한(capabilities), 비루트(non-root) 사용자 설정은 여전히 적용됩니다.

만약 KIROCREW_ALLOW_UNSANDBOXED=1을 설정한다면 무엇이 변경되는지 명확히 이해해야 합니다. 이제 컨테이너만이 에이전트와 서버 사이의 유일한 경계가 됩니다. 프로젝트의 경고를 다시 한번 강조합니다. 에이전트에게 직접 넘겨줄 의도가 없는 호스트 경로는 마운트하지 마십시오. 실제로는 Docker 소켓, /의 모든 바인드 마운트, 다른 서비스의 데이터가 포함된 디렉터리가 이에 해당합니다.

나머지는 명령 실행이 허용된 모든 에이전트에 적용되는 기본 틀입니다. 에이전트의 자격 증명은 필요한 단일 저장소나 버킷으로만 범위를 제한하십시오. 계정 전체 권한을 가진 개인 토큰은 절대 사용하지 마십시오. VPS에서 최소 권한 사용자 사용하기에서 설명하는 것처럼, 다른 파일이 없는 전용 사용자로 에이전트를 실행하십시오. 에이전트가 코드를 작성하고 실행할 때는 망가져도 되는 머신을 제공하십시오. 코딩 에이전트를 위한 일회용 VM은 이 compose 파일의 어떤 플래그보다 강력한 경계가 됩니다. 파일을 정리하는 대신 VM 자체를 삭제하면 되기 때문입니다. 동일한 논리가 VPS에서 OpenClaw 안전하게 실행하기와 VPS에서 Hermes 에이전트 자체 호스팅하기에도 적용됩니다. 도구 또한 폭발 반경에 포함됩니다. 에이전트에게 웹 검색 기능을 제공하면 에이전트가 가져오는 모든 페이지가 신뢰할 수 없는 입력값이 됩니다. 따라서 자체 SearXNG 인스턴스 연결하기는 인프라 구성인 동시에 프롬프트 인젝션을 방어하기 위한 결정이기도 합니다. 예약된 작업은 잠든 사이에도 비용을 발생시킵니다. Kiro 백엔드에서의 추론은 사용자의 Kiro 플랜을 사용하므로, 야간 작업을 추가하기 전에 VPS에서 AI 에이전트 비용 제어하기에 설명된 제한 사항을 설정하십시오.

업그레이드 전 상태 볼륨 백업

먼저 실제 볼륨 이름을 찾습니다. Compose는 프로젝트 이름을 접두사로 사용하여 명명된 볼륨을 생성하며, 프로젝트 이름은 기본적으로 디렉터리 이름입니다. 따라서 /opt/kirocrew/compose.yaml 내에서 kirocrew-home으로 선언된 볼륨은 kirocrew_kirocrew-home로 생성됩니다.

docker volume ls

데이터를 복사하기 전에 게이트웨이를 중지합니다. memory.db과 memory_index.db는 SQLite 데이터베이스입니다. 데이터베이스에 쓰기 작업이 진행되는 도중에 복사하면 트랜잭션이 절반만 기록될 수 있으며, 이를 복원하면 파일이 손상됩니다. 프로젝트의 마이그레이션 지침에서도 게이트웨이가 중지된 상태에서만 데이터를 이동하라고 명시합니다. 이 '중지 후 작업' 규칙은 KiroCrew에만 국한되지 않습니다. 만약 사진 서버를 함께 운영 중이라면, PhotoPrism과 Immich 비교 문서에서 각 서비스에 필요한 정확한 백업 명령어를 확인할 수 있습니다.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

아카이브를 서버 외부로 복사합니다. 복원 작업은 컨테이너를 중지한 상태에서 tar czf 대신 tar xzf를 사용하여 동일한 명령어를 실행하면 됩니다.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

새 호스트로 이전하는 작업은 제자리에서 복원하는 작업과는 다르며, 프로젝트에서 별도로 명시하고 있습니다. workspace/memory/ 하위의 채팅 기록과 프로젝트 노트는 그대로 유지되며, 두 개의 데이터베이스 파일과 config.json도 마찬가지입니다. PID 파일, 보안 이벤트 로그, .env는 이전 호스트에 종속되므로 이전하지 말고 새 서버에서 비밀 정보를 다시 입력하십시오.

잘못된 업그레이드를 롤백하는 방법

업그레이드 과정은 짧으며, 버전을 고정(pin)했기 때문에 안전합니다. 먼저 백업을 수행한 다음 태그를 변경하십시오.

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d은 이미 서버에 이미지가 없는 경우에만 이미지를 가져오므로, 태그 수정이 업그레이드의 전부입니다. 롤백 역시 이전 버전 번호를 사용하여 동일한 순서로 진행하며, 버전 태그는 변경 불가능하므로 이전에 사용하던 것과 정확히 동일한 이미지를 얻게 됩니다.

바이너리는 깔끔하게 롤백됩니다. 하지만 상태(state)는 그렇지 않을 수 있습니다. 더 최신 버전의 게이트웨이는 config.json을 다시 작성하거나 메모리 데이터베이스를 이전 버전의 게이트웨이가 읽을 수 없는 형태로 마이그레이션할 수 있으며, 2026년 10월 12일 기준으로 상태에 대한 다운그레이드 경로는 문서화되어 있지 않습니다. 설치 가이드에서는 한 가지 사례를 명확히 언급합니다. 기존 ~/.kirocrew 홈에서 이동된 데이터는 롤백이 불가능하며, ~/.kiro/crew 이전의 릴리스는 빈 상태로 시작됩니다. 따라서 이전 이미지를 실행했는데 비정상적으로 동작한다면 디버깅을 시도하지 마십시오. 해당 서비스를 중지하고 업그레이드 전에 수행한 백업을 복원한 뒤 다시 시작하십시오. 이것이 바로 백업을 먼저 수행해야 하는 이유이며, 업그레이드를 먼저 하고 백업을 나중에 하는 습관이 이처럼 초기 단계의 프로젝트에서 실패하는 이유입니다.

여기서 검증되지 않은 사항

이 소프트웨어의 연식에 대해 솔직히 말씀드리겠습니다. 버전 0.1.3는 2026년 8월 5일에 출시되었으며, 2026년 10월 12일 기준으로 안정화 버전은 0.8.0에 도달했습니다. 대부분의 릴리스 노트는 여전히 자동화된 변경 로그 수준입니다. 0.8.0 노트는 직접 작성되었으나 마이그레이션 섹션이 포함되어 있지 않으며, 공개된 릴리스 이력은 약 3개월 정도에 불과합니다. 이 가이드의 내용은 장기적인 운영 결과가 아니므로, 메모리 증가, 데이터베이스 크기, 스케줄러 신뢰성은 가정하지 마시고 직접 서버에서 측정하십시오.

의존성을 갖기 전에 직접 테스트해 볼 가치가 있는 동작이 두 가지 있습니다. 첫째, 더 최신 버전에서 기록된 상태를 이전 버전으로 다운그레이드했을 때 읽을 수 있는지 확인하십시오. 이는 장애 상황이 아닐 때 볼륨 복사본으로 테스트해야 합니다. 둘째, 예약된 작업이 실행될 시점에 Kiro 로그인이 만료되면 게이트웨이가 어떻게 동작하는지 확인하십시오. 두 가지 모두 초기 프로젝트에서 릴리스를 거치며 조용히 다듬어지는 거친 부분들이며, 지금 확인하는 것은 비용이 거의 들지 않습니다.

FAQ

KiroCrew 대시보드가 서버의 공인 IP에서 열리지 않는 이유는 무엇입니까?

제공된 예제는 포트를 루프백 주소에 바인딩하기 때문입니다. -p 127.0.0.1:5476:5476는 컨테이너 포트를 호스트의 루프백 주소에만 매핑하도록 의도적으로 설정되어 있습니다. ssh -N -L 5476:127.0.0.1:5476 you@your-server을 사용하여 SSH로 포트를 포워딩한 다음, 노트북에서 http://localhost:5476/?token=<token>에 접속하십시오. 127.0.0.1: 접두사를 제거하여 외부에서 접근할 수 있게 만들면 게이트웨이가 공인 인터넷에 노출됩니다. 이때 Docker의 게시된 포트 DNAT 규칙이 ufw 규칙보다 먼저 트래픽을 라우팅하므로 ufw가 이를 차단하지 못합니다. 게시된 포트를 필터링하려면 Docker의 DOCKER-USER 체인(iptables 백엔드 사용 시)이나 별도의 nftables 기본 체인(nftables 백엔드 사용 시)을 사용해야 합니다. 루프백 바인딩을 유지하는 것이 더 간단합니다.

KiroCrew는 데이터를 어디에 저장하며, 무엇을 백업해야 합니까?

모든 데이터는 ~/.kiro/crew 아래에 위치합니다. 이는 컨테이너 이미지 내부의 /home/kirocrew/.kiro/crew에 해당하며, KIROCREW_HOME를 통해 위치를 변경할 수 있습니다. 게이트웨이를 중지한 상태에서 해당 디렉터리 전체 또는 Docker 볼륨 전체를 백업하십시오. memory.db과 memory_index.db는 SQLite 데이터베이스이므로, 게이트웨이가 데이터를 쓰는 도중에 복사하면 데이터가 일관되지 않을 수 있습니다. 새 호스트로 이전할 때는 workspace/memory/, 두 개의 데이터베이스 파일, 그리고 config.json을 옮기면 됩니다. PID 파일, 보안 이벤트 로그, .env은 이전 호스트의 데이터이므로 옮길 필요가 없습니다.

stable 태그를 사용해야 합니까, 아니면 버전 태그를 사용해야 합니까?

버전 태그를 사용하십시오. stable는 릴리스가 나올 때마다 변경되므로, 다음 pull 시점에 실행 중인 버전이 예고 없이 바뀔 수 있으며 태그 자체로는 현재 실행 중인 버전을 알 수 없습니다. 0.8.0과 같은 버전 태그는 변경되지 않으므로 롤백이 가능합니다. 이전 버전 번호로 되돌리면 동일한 이미지를 다시 사용할 수 있습니다. 2026년 11월 1일 기준 최신 안정 릴리스는 0.11.1입니다.

에이전트가 명령 실행을 거부하는 이유는 무엇입니까?

컨테이너는 처음 시작될 때 샌드박스 지원 여부를 확인합니다. 에이전트 하위 프로세스를 격리할 수 없고 KIROCREW_ALLOW_UNSANDBOXED=1가 설정되어 있지 않으면, 보안되지 않은 상태로 실행하는 대신 실행 자체를 거부합니다. 이 경우 게이트웨이는 정상으로 보이지만 모든 작업이 중단됩니다. docker logs kirocrew을 확인하면 첫 실행 시의 샌드박스 결정 사항을 볼 수 있습니다. 이 변수를 설정하면 컨테이너가 에이전트와 호스트 사이의 유일한 경계가 되므로, 설정 시 에이전트에 직접 넘겨주지 않을 파일은 마운트하지 마십시오.

KiroCrew를 직접 호스팅하려면 Kiro 계정이 필요합니까?

2026년 11월 1일 기준으로 Kiro 백엔드를 사용하려면 계정이 필요합니다. KiroCrew는 Apache 2.0 라이선스를 따르는 자유 소프트웨어이지만, 해당 백엔드에서의 추론은 사용자의 Kiro 플랜을 사용합니다. 고정된 0.8.0 컨테이너는 Kiro CLI를 사용합니다. docker exec -it kirocrew kiro-cli login를 실행하고 브라우저에서 기기 코드를 승인하거나, 자동화를 위해 KIRO_API_KEY을 컨테이너 환경 변수로 전달하십시오. 인증이 구성되기 전까지는 게이트웨이가 시작되고 대시보드가 로드되지만, 기본 하네스에는 통신할 모델이 없습니다. 0.10.0부터는 kiro-cli을 설치할 필요가 없는 내장 KAS 엔진이 포함되었습니다. 0.11.0는 저장된 하네스 설정이 없는 신규 설치 시 KAS를 기본값으로 설정하며, 기존 Kiro CLI 선택 사항은 유지합니다. KAS는 kiro-cli login 대신 Crew 자체 로그인을 사용합니다. 프로젝트의 사용자 정의 백엔드 가이드를 따르면 claude 하네스를 통해 메인 모델의 대화 내용을 사용자가 선택한 Anthropic 호환 엔드포인트로 보낼 수 있지만, Kiro 전용 기능을 사용하려면 여전히 kiro-cli 로그인이 필요합니다.

이 글이 도움이 되었나요?