KiroCrew 설치 및 사용 방법
KiroCrew 란?
KiroCrew(Kiro Crew)는 로컬 또는 원격 장비에서 상주하며 동작하는 오픈소스 AI 에이전트입니다. Gateway 라고 불리는 장기 실행 프로세스가 하나 떠 있고, 이 Gateway 에 데스크톱 앱, 웹 대시보드, CLI 로 접속하거나 Slack, Telegram, Discord, Teams 같은 메신저 채널을 연결해서 같은 에이전트를 여러 경로로 사용하는 구조입니다. 예약 작업(cron), 서브에이전트 병렬 실행, 지식 베이스 같은 기능이 Gateway 안에 함께 들어 있습니다.
LLM 호출은 kiro-cli 를 통해 이루어지며, KiroCrew 는 ACP(Agent Client Protocol) 로 kiro-cli 를 구동합니다. 즉 별도의 API 키를 준비하지 않고 kiro-cli 로그인 계정을 그대로 사용합니다.
저의 경우 EC2 인스턴스에 KiroCrew 를 상주형으로 올려두고, 텔레그램을 통해 사용하는 형태로 테스트를 해보았습니다. 이번 포스팅에서는 그 과정을 따라가며 KiroCrew 설치와 기본 사용 방법에 대해 기록하도록 하겠습니다.
테스트 환경
- 테스트 환경: Amazon Linux 2023 (EC2)
- KiroCrew: 0.4.1rc1
- 에이전트 런타임: kiro-cli
설치
아래와 같이 설치 스크립트를 통해 KiroCrew 를 설치합니다.
[ec2-user@ip-172-31-1-182 ~]$ curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
Resolving KiroCrew (stable channel) ...
Verified signed manifest.
Downloading kirocrew 0.4.1rc1 ...
Verified SHA-256.
Installing into managed venv at /home/ec2-user/.kiro/crew-venv ...
Installed kirocrew 0.4.1rc1 (channel: stable).
Next steps:
kirocrew gateway # start the dashboard now (http://localhost:5476)
kirocrew service install # run it 24/7 as a service (survives logout, restarts on crash)
kirocrew --help # everything else
Need a non-default port (e.g. 5476 is already taken)? Set it at install time;
it is baked into the service unit:
KIROCREW_PORT=5477 kirocrew service install
위와 같이 전용 venv(/home/ec2-user/.kiro/crew-venv) 에 설치가 완료된 것을 확인 할 수 있습니다. 설치 안내에도 나오듯이 kirocrew gateway 로 포그라운드 실행이 가능하지만, SSH 세션이 끊어지면 함께 종료되기 때문에 서버에 상주시킬 경우에는 서비스로 등록하는 것이 좋습니다.
서비스 등록
아래와 같이 systemd 서비스로 등록합니다. 저의 경우 기본 포트(5476) 대신 5477 을 사용하도록 KIROCREW_PORT 를 지정했습니다. 이 값은 설치 시점에 서비스 유닛에 그대로 반영됩니다.
[ec2-user@ip-172-31-1-182 ~]$ KIROCREW_PORT=5477 kirocrew service install
✅ kirocrew service installed and started.
unit: /etc/systemd/system/kirocrew.service
AppArmor profile not needed: AppArmor is not an active LSM on this kernel
Status: kirocrew service status
Logs: kirocrew logs -f
Remove: kirocrew service uninstall
서비스 구동 점검
아래와 같이 서비스 상태를 확인합니다.
[ec2-user@ip-172-31-1-182 ~]$ kirocrew service status
● kirocrew.service - Kiro Crew gateway (dashboard + Slack + cron)
Loaded: loaded (/etc/systemd/system/kirocrew.service; enabled; preset: disabled)
Active: active (running) since Mon 2026-08-31 05:36:37 UTC; 1min 2s ago
Docs: https://github.com/kirodotdev/KiroCrew
Main PID: 2873819 (kirocrew)
Tasks: 20 (limit: 18660)
Memory: 733.5M
CPU: 4.890s
CGroup: /system.slice/kirocrew.service
└─2873819 /home/ec2-user/.kiro/crew-venv/bin/python3.11 /home/ec2-user/.local/bin/kirocrew gateway --no-open
Aug 31 05:36:37 ip-172-31-1-182.ap-northeast-2.compute.internal systemd[1]: Started kirocrew.service - Kiro Crew gateway (dashboard + Slack + cron).
위와 같이 서비스가 active (running) 상태이며, kirocrew gateway --no-open 으로 기동된 것을 확인 할 수 있습니다.
다음 실제로 대시보드 포트가 열려 있는지 확인합니다.
[ec2-user@ip-172-31-1-182 ~]$ netstat -antp | grep 5477
(Not all processes could be identified, non-owned process info
will not be shown, you would have to be root to see it all.)
tcp 0 0 127.0.0.1:5477 0.0.0.0:* LISTEN 2875521/python3.11
위와 같이 지정한 5477 포트가 LISTEN 상태인 것을 확인 할 수 있습니다. 주의할 점은 바인딩 주소가 0.0.0.0 이 아니라 127.0.0.1 이라는 부분입니다. 대시보드는 기본적으로 루프백에만 바인딩되므로 외부에서 직접 접근할 수 없고, SSH 터널이나 별도의 설정을 통해 접근해야 합니다.
이어서 해당 프로세스를 확인합니다.
[ec2-user@ip-172-31-1-182 ~]$ ps -ef | grep 2875521
ec2-user 2875521 1 6 05:39 ? 00:00:03 /home/ec2-user/.kiro/crew-venv/bin/python3.11 /home/ec2-user/.local/bin/kirocrew gateway --no-open
ec2-user 2875713 2875521 0 05:39 ? 00:00:00 /home/ec2-user/.kiro/crew-venv/bin/python3.11 /home/ec2-user/.kiro/crew/run/kirocrew_sandbox_2875521_8s52ompr.py /home/ec2-user/.local/bin/kiro-cli acp --agent kirocrew-lite
위와 같이 Gateway 프로세스 하위에 kiro-cli acp 프로세스가 자식으로 떠 있는 것을 확인 할 수 있습니다. Gateway 가 kiro-cli 를 ACP 로 구동해서 모델을 호출하는 구조가 프로세스 트리에도 그대로 드러납니다.
타임존 설정
예약 작업(cron) 을 사용할 경우 타임존을 먼저 맞춰두는 것이 좋습니다. 아래와 같이 설정합니다.
[ec2-user@ip-172-31-1-182 ~]$ kirocrew config set timezone Asia/Seoul
✅ timezone = "Asia/Seoul"
설정 값을 변경하면 세션 풀이 자동으로 재시작되어 즉시 반영됩니다.
리모트 세션 (원격 Crew) 연결 설정
KiroCrew 는 데스크톱 앱에서 SSH 터널을 통해 원격 호스트의 Gateway 에 접속할 수 있습니다. 저의 경우 로컬 맥에서 데스크톱 앱을 실행하고, 위에서 구성한 EC2 인스턴스의 Gateway 에 붙는 형태로 테스트를 진행했습니다.
먼저 아래와 같이 로컬의 SSH 설정에 대상 호스트가 등록되어 있어야 합니다.
$ cat ~/.ssh/config | grep oui -A4
Host oui
Hostname 123.123.123.123
User ec2-user
IdentityFile ~/.ssh/private.pem
Port 22
앱에서 별도로 비밀번호를 입력할 수 없기 때문에, 대화형 입력 없이 접속 가능한 키 기반 SSH 설정이 필요합니다.
아래와 같이 원격 Crew 를 연결하기 위해서 설정 > 원격 Crew 를 선택하고 리모트 세션을 위한 정보를 추가합니다. 이름, 연결 방식(SSH 터널), SSH 호스트 또는 별칭, 리모트 포트, 토큰 TTL 을 입력합니다. 리모트 포트에는 원격 Gateway 가 사용하는 포트(이번 테스트에서는 5477) 를 지정합니다.
리모트 세션 접근 설정이 완료된 모습입니다.
위와 같이 Connected 상태가 되면 연결이 정상적으로 이루어진 것을 확인 할 수 있습니다.
리모트 세션과 로컬 세션은 왼쪽 상단에 버튼을 통해 전환이 가능합니다.
사용량 점검
설정 > 개요 에서 요금제와 크레딧 사용량, 최근 30일간의 세션 활동을 확인할 수 있습니다.
위와 같이 사용한 크레딧과 초기화 예정일, 일자별 세션 및 도구 호출 횟수를 확인 할 수 있습니다.
모델 설정
설정 > 채팅 에서 용도별로 사용할 모델과 추론 강도를 지정합니다.
채팅용, 백그라운드 작업용(제목 생성, 기록 압축 등), 서브에이전트용 모델을 각각 나눠서 지정할 수 있습니다. 백그라운드 작업에는 가벼운 모델을 사용하는 방식으로 크레딧 소모를 조절하는 것이 가능합니다.
스케줄 생성
반복 작업은 스케줄 메뉴에서 관리합니다.
위와 같이 미리 정의된 템플릿(야간 빌드 감시, 오류 다이제스트 등) 으로 시작하거나, 채팅에서 자연어로 요청해서 등록하는 것도 가능합니다.
지식 베이스 생성
지식 메뉴에서는 파일을 업로드해서 검색 가능한 지식 베이스를 구성합니다.
소스 탭에서 파일을 업로드하면 항목과 엔터티, 관계가 추출되어 목록 보기와 그래프 보기에서 확인이 가능합니다.
채팅
기본적인 사용은 대시보드의 채팅 화면에서 이루어집니다.
저의 경우 연결된 MCP 서버 목록을 확인해보았는데, 위와 같이 KiroCrew 자체 기능을 제공하는 kirocrew-core, kirocrew-cron 과 함께 별도로 등록한 AWS 관련 MCP 서버들이 함께 노출되는 것을 확인 할 수 있습니다. 응답 하단에는 해당 응답에 소모된 크레딧과 소요 시간이 표시됩니다.
입력창에서는 /command, @file, $skill 형태의 문법을 사용할 수 있고, 하단에서 에이전트와 작업 디렉토리, 모델을 확인 할 수 있습니다.
에이전트 설정
에이전트 기능 메뉴에서는 에이전트 자체의 구성을 확인하고 변경합니다.
위와 같이 해당 에이전트가 사용하는 템플릿과 워크스페이스, 메모리 저장소, 모델을 한 화면에서 확인 할 수 있고, 작업이 들어오는 경로(일정, 트리거, 웹훅) 도 함께 표시됩니다.
스킬은 특정 작업에 필요할 때 에이전트가 불러오는 지식 파일입니다.
각 스킬에는 트리거 키워드가 지정되어 있어서, 해당 키워드가 일치할 때만 내용이 프롬프트에 삽입되는 방식으로 동작합니다. 스킬 추가나 변경 후에는 상단의 적용 후 재시작 버튼을 눌러야 반영됩니다.
스티어링은 항상 적용되는 규칙 파일입니다.
~/.kiro/steering 과 프로젝트의 .kiro/steering 에 위치한 Markdown 파일이 항상 프롬프트에 포함됩니다. 저의 경우 AWS 작업 시 준수할 규칙과 시크릿 처리 규칙을 스티어링으로 등록해두고 사용하고 있습니다. 필요할 때만 불러오는 스킬과 달리 스티어링은 상시 적용되므로, 예외 없이 지켜야 하는 규칙만 등록하는 것이 좋습니다.
터미널 기능
대시보드 하단에서 터미널을 바로 열 수 있습니다.
위와 같이 Gateway 가 동작하는 호스트의 셸이 열리므로, 에이전트가 수행한 작업을 같은 화면에서 바로 확인하는 용도로 사용이 가능합니다.
채널 연결
테스트를 위해 텔레그램 채널을 연결해보겠습니다. 설정 > 채널 에서 연결 가능한 플랫폼 목록을 확인 할 수 있습니다.
텔레그램은 롱 폴링 방식의 Bot API 를 사용하므로, 웹훅이나 공개 주소가 필요하지 않습니다. 대시보드를 외부에 노출하지 않은 상태에서도 사용이 가능하다는 점이 장점입니다.
먼저 텔레그램 봇을 생성합니다. 텔레그램에서 @BotFather 를 검색해서 대화를 시작합니다.
아래와 같이 /newbot 을 전송하고 안내에 따라 봇 이름을 입력합니다.
봇 사용자명까지 입력하면 아래와 같이 봇 생성이 완료되고 토큰이 발급됩니다.
생성된 봇의 토큰을 입력합니다. 대시보드에서 입력하면 아래 경로에 저장됩니다.
[ec2-user@ip-172-31-1-182 ~]$ cat ~/.kiro/crew/.env
TELEGRAM_BOT_TOKEN=1234567890:AAAAAAAAAAAAAAAa000000000000
채널 토큰은 config.json 이 아니라 ~/.kiro/crew/.env 에 별도로 저장됩니다.
텔레그램 봇은 사용자명만 알면 누구나 대화를 시도할 수 있기 때문에, 허용된 사용자만 채널 사용을 승인해야 합니다. 현재 사용자 아이디 확인법은 @userinfobot 에게 메시지를 보내는 것입니다. 확인한 숫자 ID 를 허용 목록에 추가합니다.
[ec2-user@ip-172-31-1-182 ~]$ cat ~/.kiro/crew/config.json | grep -A5 telegram\" | egrep "all|ena"
"enabled": false,
"allowed_user_ids": [1234554321],
허용된 사용자 ID 를 비워두면 모든 요청이 거부되는 것이 기본 동작이므로, 설정을 누락하면 봇이 응답하지 않습니다.
설정 저장만으로는 채널이 기동되지 않기 때문에 아래와 같이 KiroCrew 를 재시작합니다.
[ec2-user@ip-172-31-1-182 ~]$ kirocrew restart
✅ Restarted kirocrew service.
🔑 http://localhost:5477?token=eyJzd...
위와 같이 재시작과 함께 대시보드 접속용 토큰 링크가 함께 출력되는 것을 확인 할 수 있습니다.
설정을 한 이후, 메뉴에서 텔레그램 사용을 선택하고 하단에 설정 저장을 선택합니다.
재시작 전에는 위와 같이 설정은 저장되었으나 채널이 실행 중이 아니라는 안내가 표시됩니다.
이후 채널이 Connected 상태가 되면 사용 준비가 완료된 것입니다.
실제 사용 테스트
연결한 텔레그램 봇으로 대화를 시도해보았습니다.
위와 같이 정상적으로 응답하는 것을 확인 할 수 있습니다. 응답 하단에는 소요 시간과 컨텍스트 사용률이 함께 표시되어 상태 확인이 가능합니다.
서브에이전트 기능 지원
조사나 분석처럼 시간이 오래 걸리는 작업은 서브에이전트로 분할해서 병렬로 처리할 수 있습니다.
위와 같이 하나의 요청을 여러 갈래로 나누어 서브에이전트를 동시에 실행하고, 각 작업의 경과 시간과 진행 상태를 확인 할 수 있습니다. 개별 중지나 전체 중지도 가능합니다.
기본 승인 모드에서는 위와 같이 도구 실행 시 승인을 요청합니다. 한 번만 허용, 신뢰, 거부 중에서 선택할 수 있으며, 반복되는 작업은 신뢰를 선택해서 이후 승인을 생략하는 것이 가능합니다. 서브에이전트를 여러 개 띄우는 경우 승인 요청도 함께 늘어나기 때문에, 작업 성격에 따라 승인 모드를 조절하는 것이 좋습니다.
정리
위와 같은 방법으로 EC2 인스턴스에 KiroCrew 를 상주형으로 구성하고, 데스크톱 앱과 텔레그램 채널을 통해 사용하는 것이 가능합니다. 정리하면 아래와 같은 순서로 진행됩니다.
- 설치 스크립트로 설치 후
kirocrew service install로 systemd 서비스 등록 kirocrew config set으로 타임존 등 기본 설정- 데스크톱 앱에서 SSH 터널 기반으로 원격 Gateway 연결
- 채널 토큰과 허용 사용자 ID 등록 후 재시작하여 메신저 연결
대시보드가 루프백에만 바인딩되는 점, 채널 설정 후 재시작이 필요한 점, 허용 사용자 ID 를 비워두면 모두 거부되는 점 정도가 처음 구성할 때 확인하면 좋은 부분입니다.
참고
- Kiro Crew 공식 문서: https://kiro.dev/docs/crew/
- Kiro Crew 설치 가이드: https://kiro.dev/docs/crew/installation/
- Kiro Crew 24/7 운영: https://kiro.dev/docs/crew/running-24-7/
- Kiro Crew CLI 레퍼런스: https://kiro.dev/docs/crew/interfaces/cli-reference/
- KiroCrew GitHub: https://github.com/kirodotdev/KiroCrew
