나의 홈랩 AI 개발 플랫폼

나는 홈랩을 더 쉽게 관리하기 위해 Git 접근 권한이 있는 OpenCode Web UI를 설정했습니다. OpenCode가 Git으로 푸시(push)하면, 내가 PR(Pull Request)을 승인하고, GitOps가 변경 사항을 배포합니다. 무엇보다 가장 좋은 점은 OpenCode가 서버로서 실행되며, 기기 간에 동기화되는 지속적인 코딩 세션(persistent coding sessions)을 제공한다는 것입니다.

곧 나의 홈랩 설정을 공유하겠습니다. 내가 관리하는 서비스들을 위해 약 12개의 Docker Compose 스택이 있습니다. 최근에는 GitOps로 관리 및 배포할 수 있도록 이들을 Arcane으로 옮겼습니다. 그다음 논리적인 단계는 내 서비스를 유지 관리하는 데 도움을 줄 AI 도구(AI tooling)를 사용하는 것이었습니다.

가장 먼저 떠오른 용도는 컨테이너 업데이트를 돕기 위해 AI를 사용하는 것이었습니다. 이전에는 각 서비스의 릴리스 노트(release notes)를 찾아보고, 중대한 변경 사항(breaking changes)이 있는지 확인하고, 업데이트를 실행한 뒤, 각 서비스에 문제가 없는지 수동으로 확인하는 데 시간을 보냈습니다. 이 작업에 몇 시간을 소비하곤 했습니다. 이제는 몇 분 만에 릴리스 노트의 요약을 읽을 수 있어 버전 업그레이드가 더 쉽고 안전해졌습니다. 게다가, 나는 AI를 사용하여 대부분의 컨테이너에 헬스체크(healthchecks)를 추가함으로써 문제를 더 빠르게 발견할 수 있게 했습니다.

OpenCode

나는 주로 Claude Code를 사용했지만, 최근 AI 제공업체들이 토큰 제한(token limits)을 통해 고객으로부터 가치를 정말 쥐어짜고 있어서 다른 옵션들을 살펴볼 기회를 가졌습니다. 나는 특정 벤더에 종속되지 않고(vendor agnostic) 주요 플러그인들을 지원하는 무언가를 원했습니다. 결국 OpenCode로 결정했습니다. 아마 다른 괜찮은 코딩 환경들도 있겠지만, 내가 시도해 본 것 중 이것이 가장 마음에 들었습니다.

그러다 이것이 내장 웹 서버와 Web UI를 함께 제공한다는 것을 알게 되었고, 한 가지 아이디어가 떠올랐습니다.

AI 개발 플랫폼

나는 Truenas 호스트에 기본적인 개발 도구가 포함된 간단한 VM을 설정하고, OpenCode 웹 서버를 systemd 유닛으로 추가했습니다. 이는 내장 터미널, 파일 브라우저, Git diff를 제공할 뿐만 아니라, 여러 코딩 세션을 동시에 관리할 수 있는 Git worktree 지원까지 갖춘 탄탄한 환경입니다. 게다가 OpenCode는 내가 본 모바일 Web UI 중에서 가장 뛰어난 질문/답변 팝업 기능을 갖추고 있었습니다.

나는 내 Git 서버에 전용 SSH 키를 가진 OpenCode만의 사용자 계정을 부여했습니다. OpenCode는 프로젝트를 클론(clone)하고 브랜치(branch)를 푸시(push)할 수 있지만, 배포(deploy) 브랜치로 직접 푸시할 수는 없습니다.

나의 워크플로우(workflow)는 AI를 PR(Pull Request) 리뷰 뒤에 배치하는 방식입니다. OpenCode가 변경 사항을 작성하면, 나는 PR에서 직접 이를 머지(merge)합니다. 이것이 귀엽게 느껴지기도 하지만, 더 중요한 점은 리뷰되지 않은 코드가 배포되는 것을 방지한다는 것입니다.

해당 VM(가상 머신)은 인터넷 접속과 내 Git 서버에 대한 접근 권한은 있지만, 실제 서비스에는 접근할 수 없습니다. 폭발 반경(blast radius)이 작기 때문에, 빌드 도구(build tools)를 설치하거나 의존성(dependencies)을 테스트해야 할 때 OpenCode에 VM의 루트(root) 권한을 부여하는 것이 마음 편합니다.

나는 이것을 프로덕션 개발자 플랫폼(production developer platform)으로 구축하는 모습도 그려볼 수 있었습니다. 사전 설치된 툴링(tooling), 접근 가드레일(access guardrails), 그리고 감사 로그(audit logs)를 갖추고 개발자에게 제공되는 휘발성 컨테이너(ephemeral containers) 같은 것 말입니다. 하지만 나에게 있어, 이 시스템은 너무 많은 가동 요소 없이 내가 필요한 기능을 수행해 줍니다.

워크플로우 (Workflow)

나의 기본적인 워크플로우는 다음과 같습니다:

• OpenCode에서 기능이나 개선 사항을 계획 (사양(spec), 구현 계획, 그리고 셀프 리뷰)
• 가능하다면 내가 변경 사항을 테스트하거나 검증
• 마음에 들지 않는 부분은 OpenCode와 함께 반복(iterate)
• OpenCode가 변경 사항을 기능 브랜치(feature branch)에 푸시
• 내가 이 브랜치에 대해 PR을 생성
• 만족스러우면 PR을 머지
• 그 이후부터는 GitOps가 담당 - Docker 서비스 변경은 Arcane, Home Assistant 설정 변경은 GitOps 플러그인, 블로그 변경은 Cloudflare Pages worker가 처리

나는 내 서비스들을 Truenas에서 Arcane GitOps 프로젝트로 마이그레이션(migrate)했습니다. 이는 주로 이전에 Truenas에서 실행하던 모든 Docker Compose 스택들을 Git 기반 저장소로 관리하기 위함이었습니다. OpenCode를 추가했을 때 이것이 얼마나 잘 작동하는지 보고 놀랐습니다. 예를 들어, 휴대폰으로 모든 컨테이너의 네트워킹을 업데이트할 수 있게 되면서 복잡하게 퍼져 있는 환경을 관리하기가 훨씬 쉬워졌습니다. 이전에는 모든 Compose 스택을 샅샅이 뒤지며 네트워크 연결성을 추적하는 데 몇 시간이 걸렸습니다. 이제는 OpenCode에 목표를 가지고 코드베이스를 가리키게 한 뒤, 결과로 나온 PR 변경 사항을 확인하고 머지하기만 하면 됩니다.

가장 핵심적으로 부족한 부분은 CI 피드백입니다. GitHub에서는 코딩 에이전트 (coding agent)가 Actions 로그를 참조하도록 설정하여, 실패한 테스트, 린터 (linter) 오류, 스택 트레이스 (stack traces), 그리고 IaC 계획 변경 사항을 진단할 수 있도록 하는 것을 선호합니다. 이는 단위 테스트 (unit tests)가 커버하지 못하는 변경 사항들에 대해 빠른 피드백 루프 (feedback loop)를 유지하는 데 도움이 됩니다.

Forgejo는 이를 더 어렵게 만듭니다. Forgejo Actions는 공개 API를 통해 작업 로그 (job logs)를 노출하지 않습니다. 문서화되지 않은 API들이 존재하지만, 저는 그것들에 의존하여 시스템을 구축하고 싶지는 않습니다.

이러한 설정 덕분에 저는 AI에게 변경하려는 서비스에 대한 직접적인 접근 권한을 부여하지 않고도, 어떤 기기에서든 홈 인프라 (home infra) 변경을 수행할 수 있습니다. 컴퓨터에서 변경을 시작하고, 휴대폰으로 PR을 검토하며, GitOps가 배포를 처리하도록 맡길 수 있습니다.