rakazo 딥다이브
— AI 동료가 멈췄다가 다시 일하는 시스템의 설계

1프로젝트 한줄 요약

rakazo는 사용자가 만든 봇에게 모델·도구·기억·실행 환경을 붙여 주는 자체 호스팅 AI 에이전트 제품입니다. 모델이 다음 행동을 제안하면, 서버가 그 행동의 실행과 기록, 대기와 재개를 관리합니다. 이 역할 분담이 전체 코드를 읽는 출발점입니다.

README는 이를 지속적으로 함께 일하는 AI 동료라고 소개합니다. 실제 데이터 모델도 그 설명과 연결됩니다. packages/db/prisma/schema.prisma에는 봇을 나타내는 Bot, 대화 단위인 Thread, 실행 한 건인 Run, 예약 작업인 Routine, 실행 컴퓨터인 Computer가 각각 있습니다. 한 봇의 존재와 한 번의 실행을 서로 다른 수명으로 다룹니다.

사용자 행동 하나를 여섯 단계로 펼치기

1. 접속: 브라우저, Electron 데스크톱, Expo 모바일에서 같은 서버에 연결합니다.
2. 설정: 사용할 모델 계정과 봇을 정하고, 필요한 컴퓨터·앱 연결을 구성합니다.
3. 접수: 대화 메시지를 보내면 API가 권한과 입력을 확인하고 메시지와 실행 상태를 저장합니다.
4. 실행: 워커가 작업을 받아 Pi 런타임에 모델 호출을 맡기고, 도구 요청을 처리합니다.
5. 대기: 질문·승인·컴퓨터 인계가 필요하면 그 상태를 기록하고 사용자의 응답을 기다립니다.
6. 복원: 결과와 이벤트를 저장하므로 클라이언트가 다시 연결돼도 뒤따라 읽을 수 있습니다.

예를 들어 외부 모델 API와 로컬 Docker 컴퓨터를 조합할 수도 있고, 로컬 모델 서버와 원격 컴퓨터를 조합할 수도 있습니다. packages/adapters/src/pi-local-provider.ts에는 로컬 모델 연결이, packages/adapters/src/sandbox-factory.ts에는 컴퓨터 제공자를 선택하는 코드가 따로 있습니다. 조합 가능성은 인터페이스가 만들며, 실제로 쓸 수 있는 도구는 각 제공자의 기능에 따라 달라집니다.

2왜 주목받는가

2026-10-23 GitHub Trending TypeScript Weekly에서 8위로 선정된 프로젝트입니다. 스타 5,309개와 포크 946개는 관심의 크기를 보여 주지만, 그 수치만으로 유입 경로나 인기의 원인을 증명할 수는 없습니다. 여기서는 관심을 끌 만한 특징을 소스에 근거해 해석합니다.

① 모델과 컴퓨터를 각각 고를 수 있다

README의 “원하는 모델과 샌드박스를 고른다”는 설명은 AgentRuntime과 SandboxProvider라는 별도 인터페이스로 구체화됩니다. 둘 다 packages/adapter-kit/src/interfaces.ts에 있습니다. 모델 SDK가 바뀔 때 화면과 데이터베이스 코드를 함께 갈아엎지 않도록 경계를 둔 점이 학습 가치입니다.

② 한 번의 답변 뒤에도 업무가 이어진다

대화 이력, 기억 문서, 예약 실행, 다른 봇에 대한 위임은 서로 다른 데이터와 도구로 표현됩니다. 특히 Run에는 상태·임대 만료 시각·체크포인트가 있고, Routine은 다음 실행을 관리합니다. “계속 일한다”는 제품 문구를 구현하려면 서버 재시작과 사용자 부재까지 다뤄야 한다는 사실을 보여 줍니다.

③ 여러 기기가 하나의 업무 상태를 본다

README와 AGENTS.md는 웹·데스크톱·모바일을 하나의 제품으로 설명합니다. Electron은 웹 UI를 호스팅하고, Expo는 네이티브 클라이언트를 제공합니다. 공유 계약과 서버 중심의 실행 관리는 기기마다 서로 다른 결과가 생기는 것을 줄이는 방향입니다. 화면의 세부 기능과 언어 지원까지 모두 같다는 뜻은 아닙니다.

이 표는 접근 방식의 차이를 설명한 것입니다. README는 Grok Bot, Meta Muse, OpenAI Dots, Instinct, OpenClaw, Hermes Agent의 대안이라고 소개하지만, 이 글은 각 제품의 최신 기능·가격·성능을 실측한 비교가 아닙니다. 특정 경쟁 제품보다 빠르거나 저렴하다고 단정하지 않습니다.

이 저장소의 학습 가치는 모델 호출을 실제로 운영할 수 있는 업무 시스템으로 확장하는 과정을 볼 수 있다는 데 있습니다. 어댑터 하나를 교체하는 문제와, 재시도 중 외부 행동을 중복 실행하지 않는 문제를 함께 배울 수 있습니다.

3기술 스택 전체 지도

이 저장소는 pnpm-workspace.yaml로 연결한 모노레포입니다. apps/*, packages/*, 샌드박스 supervisor, updater를 묶으며 해당 범위의 package.json은 20개입니다. 아래 버전은 커밋 8c65bc7의 각 의존성 선언값입니다. 범위 없는 고정 버전이 많지만 모든 패키지가 같은 도구 버전을 쓰지는 않습니다.

백엔드: 요청 접수와 업무 실행을 분리한다

apps/api/src/app.ts는 인증·저장소·런타임·커넥터 등을 조립하고, apps/worker/src/index.ts는 실행기와 작업 호스트를 조립합니다. HTTP 서버인 Hono가 모델을 직접 구현하는 것도, Graphile Worker가 봇의 상태 전체를 정의하는 것도 아닙니다. 각각의 역할 사이에 저장된 도메인 상태가 있습니다.

프론트엔드: 공유 규칙 위에 기기별 화면을 얹는다

루트 package.json의 override는 React와 React DOM을 19.2.3으로 맞춥니다. 반면 TypeScript는 루트·대부분 서버 패키지에서 7.0.2, 모바일·Astro 사이트에서 6.0.3입니다. README의 “TypeScript, React 19”라는 요약만으로는 보이지 않는 차이입니다.

외부 기능 연결: SDK는 어댑터 안에 모은다

위 SDK 버전 중 supervisor를 제외한 선언 위치는 packages/adapters/package.json입니다. CreateOS·Railway·Pipedream 같은 기능도 있지만, 모든 기능이 같은 형태의 전용 SDK를 의존성으로 갖는다고 가정해서는 안 됩니다. 제공자별 파일과 생성 코드를 함께 읽어야 합니다.

인프라·빌드·검증: 실행 방법도 아키텍처의 일부다

• 런타임: 루트 engines.node는 ^22.22.2 || ^24.0.0 || >=26.0.0. Node 23·25는 이 범위에 없습니다.
• 패키지 관리: packageManager는 pnpm@9.15.0. pnpm-lock.yaml이 설치 해석을 고정합니다.
• 작업 그래프: Turborepo 2.11.9. turbo.json의 build는 ^build와 ^generate를 먼저 요구합니다.
• 서버 빌드: scripts/build-server.mjs를 앱의 build 스크립트가 호출하며 루트에는 esbuild 0.28.2가 선언됩니다.
• 코드 검사: Biome 2.5.15, Vitest 4.1.12. 모바일은 Vitest 4.1.11을 별도로 선언합니다.
• 실제 화면 검증: 웹·데스크톱의 Playwright 1.64.1. packages/testkit에는 PostgreSQL용 Testcontainers 12.2.1이 있습니다.
• 배포: infra/compose/Dockerfile은 digest가 고정된 node:22-bookworm 기반입니다. Compose의 PostgreSQL 기본 이미지는 postgres:16입니다.

.github/workflows/ci.yml에는 lint, 타입 검사, 빌드, 단위 테스트, PostgreSQL 통합 여정, 웹 E2E가 나뉘어 있습니다. 데스크톱 화면 검증은 Linux 가상 디스플레이에서 실행하도록 구성됩니다. 이는 정의된 검증 경로이며 특정 커밋의 모든 실행이 통과했다는 결과 보고는 아닙니다.

4아키텍처 심화 분석

아래는 기본적인 Docker·PostgreSQL 배포를 중심으로 그린 구조도입니다. 화살표는 주요 의존·데이터 흐름입니다. 선택 기능인 음성·결제·외부 메모리·메신저와 초기화·업데이트 서비스는 생략했습니다. API와 워커가 여러 어댑터를 공유하므로 모든 모델·도구 호출이 오직 한 프로세스에서만 발생한다고 해석하면 안 됩니다.

패턴 1. 포트와 어댑터 + 의존성 주입

packages/adapter-kit/src/interfaces.ts는 외부 시스템을 호출하는 통로를 인터페이스로 정의합니다. AgentRuntime, SandboxProvider, MemoryStore, JobPublisher가 대표적입니다. 실제 구현을 바깥에서 골라 전달하므로 실행 로직은 “어느 회사 SDK인가”보다 “어떤 일을 요청할 수 있는가”에 의존합니다.

// packages/adapter-kit/src/interfaces.ts에서 발췌
export interface AgentRuntime {
  describe(): AdapterDescriptor<AgentRuntimeCapabilities>;
  run(
    request: AgentRunRequest,
    context?: Partial<AdapterContext>,
  ): AsyncIterable<AgentRuntimeEvent>;
  abort(runId: string): Promise<void>;
}

여기서 AsyncIterable은 결과를 한 번에 돌려주는 대신, 시간이 지나며 여러 이벤트를 내보낸다는 계약입니다. 호출자는 for await...of로 텍스트·도구 요청·완료 같은 사건을 차례로 처리할 수 있습니다. 그 계약에 Pi 기반 구현과 테스트용 구현이 모두 들어맞습니다.

apps/worker/src/index.ts의 main()은 AGENT_RUNTIME === "scripted"이면 ScriptedAgentRuntime, 아니면 PiAgentRuntime을 만듭니다. 이어 createRunExecutor({ runtime, sandbox, memory, jobs, ... })로 필요한 구현을 전달합니다. 이런 조립 지점을 구성 루트라고 부릅니다.

// packages/adapters/src/sandbox-factory.ts에서 발췌
case "docker":
  return new DockerSandboxProvider(
    opts.supervisorUrl ?? "http://127.0.0.1:7091",
    opts.supervisorToken,
  );
case "fake":
  return new FakeSandboxProvider();

createSandboxProvider()는 다른 분기에서 E2B·Daytona·CreateOS·Boat·Railway 등을 선택합니다. 환경변수 해석은 packages/adapters/src/sandbox-provider-env.ts의 resolveSandboxProvider()가 담당합니다. 원격 제공자를 지정했어도 필수 키가 없으면 none으로 내려가는 경로가 있습니다. “앱이 켜졌다”와 “컴퓨터 작업이 가능하다”는 다른 상태입니다.

패턴 2. 내구성 있는 작업 큐 + 상태 재조정

apps/api/src/router.ts의 threads.send는 모델 설정과 대화 대상을 확인한 뒤 apps/api/src/thread-target.ts의 sendThreadMessage()를 호출합니다. 이 함수에는 clientNonce로 기존 전송을 재확인하는 경로와 데이터베이스 트랜잭션이 있습니다. 새 요청과 이미 접수된 요청을 구분하는 장치입니다.

실행을 깨우는 enqueueRunsNeedingContinue()는 같은 파일에 있습니다. 여기에는 큐 등록이 실패해도 이미 저장된 queued 실행은 남으며 reconciler가 복구한다는 주석과 오류 처리 코드가 있습니다. 메시지 수신과 모델 실행을 하나의 긴 HTTP 요청으로 묶지 않습니다.

// packages/adapter-kit/src/background-jobs.ts에서 발췌
export function runContinueJob(runId: string): BackgroundJob {
  return {
    name: "run.continue",
    payload: { runId },
    replaceKey: runJobKey(runId),
  };
}

작업 페이로드에는 전체 대화나 키를 복사하는 대신 식별자인 runId를 넣습니다. packages/adapters/src/wakeup.ts의 GraphileJobPublisher.enqueue()는 이를 utils.addJob()으로 등록하며 replaceKey를 Graphile의 jobKey로 전달합니다. 중복 키 처리에서는 남은 시도 횟수와 오래된 잠금도 고려합니다.

packages/adapters/src/job-reconciler.ts의 createJobReconciler()는 기본 30_000ms 간격으로 저장 상태를 점검합니다. createPostgresReconciliationLeadership()는 PostgreSQL advisory lock으로 조정 담당자를 정합니다. 워커가 여럿일 때 모두가 같은 복구 점검을 주도하지 않도록 하는 구성입니다.

이것을 “모든 외부 행동이 정확히 한 번 실행된다”는 보장으로 확대하면 안 됩니다. 큐 중복 제어, 실행 임대, clientNonce, 외부 효과 기록은 서로 다른 경계의 중복을 다룹니다. 원격 API에서 행동은 성공했지만 응답만 사라진 경우에는 해당 제공자의 멱등성 지원까지 고려해야 합니다.

패턴 3. 상태 머신 + 임대와 세대 번호

packages/core/src/run-state.ts에는 허용된 상태 전이 표와 canTransition(), assertTransition(), nextFence()가 있습니다. 버튼마다 상태 문자열을 임의로 바꾸는 대신 공통 규칙을 만듭니다. 아래는 주요 경로를 추린 그림이며 모든 취소·복구 경로를 나타낸 것은 아닙니다.

packages/adapters/src/executor.ts의 createRunExecutor()가 반환하는 continueRun(runId, workerId)는 조건부 updateMany()로 실행을 선점합니다. 상태와 기존 선점 조건이 맞는 행 하나를 바꿔야 다음 단계로 갑니다. 확인한 뒤 수정하는 두 동작 사이에서 다른 워커가 끼어드는 경쟁을 줄이는 방식입니다.

// continueRun()의 선점 데이터와 결과 검사 부분 발췌
data: {
  status: "leased",
  leaseOwner: workerId,
  leaseFence: fence,
  leaseExpiresAt: new Date(Date.now() + 5 * 60_000),
  error: null,
  checkpoint: null,
},
});
if (leased.count !== 1) return;

leaseFence는 nextFence(run.leaseFence)로 증가시킵니다. 이어 running으로 바꾸는 쓰기에도 leaseOwner와 leaseFence를 조건으로 넣습니다. 이전 담당자가 늦게 돌아와 최신 담당자의 상태를 덮어쓰는 문제를 막는 데 쓰는 값입니다. 예시의 5분은 최초 임대 만료 설정이며 모든 작업이 5분에 종료된다는 뜻은 아닙니다.

waiting_input은 활성 상태지만 새 작업의 진입을 막는 목록에서는 제외됩니다. waiting_takeover는 그 목록에 남습니다. QUEUE_HOLDING_RUN_STATUSES와 해당 테스트를 나란히 읽으면 “사용자에게 질문 중”과 “컴퓨터를 사용자에게 넘긴 상태”가 왜 다르게 취급되는지 추론할 수 있습니다.

패턴 4. 이벤트 기록 + 알림 + 커서로 이어받기

packages/db/prisma/schema.prisma의 Event에는 대화별 순서인 seq가 있고 @@unique([threadId, seq])가 선언됩니다. packages/db/src/events.ts의 followThreadEvents()는 마지막으로 읽은 순번 뒤의 이벤트를 데이터베이스에서 읽어 내보냅니다.

// followThreadEvents()의 읽기 루프에서 발췌
const events = await eventsAfter(prisma, threadId, seq, EVENT_BATCH_SIZE);
batchSize = events.length;
for (const event of events) {
  seq = event.seq;
  yield mapProductEvent(event);
}

EVENT_BATCH_SIZE는 200입니다. packages/adapters/src/realtime.ts의 PostgresRealtimeFanout은 LISTEN과 pg_notify로 새 기록이 있음을 알립니다. 알림이 전체 기록을 대신하는 구조는 아닙니다. 구독자는 신호를 받으면 저장된 이벤트를 읽고, 알림이 없어도 주기적으로 뒤처진 기록을 확인합니다.

그 확인 간격은 realtime 사용 시 기본 30_000ms, 알림 없이 폴링만 할 때 400ms입니다. RPC 구독은 apps/api/src/router.ts의 threads.subscribe에서 연결되며 20_000ms 하트비트와 세션 재확인 경로도 있습니다. 세션 재확인 기준은 10_000ms이지만 실제 확인은 이벤트 전달 또는 하트비트 시점에 일어납니다.

실시간 알림은 빨리 알려 주는 신호이고, 연결이 끊겼을 때 복구할 근거는 저장된 이벤트입니다. apps/web/src/pages/Shell.tsx의 rpc.threads.subscribe({ ..., cursor }, { signal })가 이 서버 계약을 소비하는 예입니다.

권한과 승인: 위 흐름 전체를 감싸는 경계

클라이언트가 전달한 대화 ID만으로 모든 데이터를 읽지 않습니다. API의 대상 해석·멤버십 검사와 함께 packages/db/src/row-security.ts가 runAsTenant()로 공간·사용자 문맥을 전달합니다. runAsSystem(reason, fn)은 여러 공간을 다뤄야 하는 명시적 우회 경로입니다. 실제 보호는 전용 앱 DB 계정과 적용된 정책이 함께 있어야 성립합니다.

도구 승인 규칙은 packages/core/src/action-approval.ts에서 읽을 수 있습니다. connectorToolRequiresApproval()는 선언된 쓰기 여부와 도구 이름의 변경 동작을 검사합니다. 다만 shell·write_file 등이 기본 승인 면제 목록에 있으므로 “모든 파일 쓰기와 명령이 매번 승인된다”고 설명하면 틀립니다. 승인 정책과 컴퓨터 격리·호스트 권한은 함께 검토해야 합니다.

5디렉토리 구조 해부

세 가지 경로를 먼저 기억하기

폴더 분리가 항상 파일 크기까지 작게 만든다는 뜻은 아닙니다. apps/api/src/router.ts와 packages/adapters/src/executor.ts는 많은 기능을 담고 있습니다. 처음부터 파일 전체를 읽기보다 함수 이름을 검색하고 호출자·반환 타입·저장하는 필드를 따라가면 부담을 줄일 수 있습니다.

코드 규모를 읽는 기준

Git 추적 파일은 2,795개입니다. 확장자로 분류한 TypeScript는 .ts 442,549줄, .tsx 103,563줄로 합계 546,112줄입니다. 이 합계 중 파일명에 .test.가 있거나 경로에 /e2e/가 있는 파일은 291,901줄입니다. 나머지 254,211줄에도 테스트 보조 코드 등이 포함될 수 있습니다.

이 수치는 빈 줄·주석·선언 파일까지 포함한 물리적 줄 수입니다. 구현 규모나 품질·테스트 커버리지의 측정값이 아닙니다. lockfile, JSON, 문서, 이미지 등을 더한 전체 저장소 텍스트 줄 수와도 다릅니다. 언어별 나머지 집계는 마지막 상태 표에 정리했습니다.

6학습 포인트 (기술별)

TypeScript·Zod: 타입과 실제 입력 검증의 차이

TypeScript 타입은 편집기와 컴파일러가 사용하는 약속입니다. 네트워크로 들어온 JSON이 그 약속을 지키는지는 별도로 확인해야 합니다. packages/contracts/src/rpc.ts는 oRPC와 Zod로 API 계약을 표현하고, packages/adapter-kit/src/background-jobs.ts의 parseBackgroundJob()는 작업 이름에 맞는 페이로드를 검증합니다.

// packages/adapter-kit/src/background-jobs.ts의 스키마 일부
"run.continue": z.object({ runId: z.string().min(1) }),
"routine.wakeup": z.object({
  routineId: z.string().min(1),
  scheduledFor: z.string().datetime({ offset: true }),
}),

실습 아이디어: { runId: "" }, { runId: 42 }, { runId: "run-demo" }를 종이에 써 두고 어느 단계에서 거절되는지 예상해 보세요. 타입을 강제로 단언하는 as와 parse()가 왜 같은 검증이 아닌지 설명할 수 있으면 좋습니다.

비동기 프로그래밍: 완료 한 번과 사건 여러 번

Promise는 나중에 값 하나를 받는 표현이고, AsyncIterable은 시간이 흐르는 동안 값을 여러 번 받는 표현입니다. AgentRuntime.run()과 followThreadEvents()가 후자입니다. 취소에는 AbortSignal이 전달되며 구독을 닫을 때 정리할 작업도 생깁니다.

// 개념 실습용 독립 예제: 저장소 코드의 복사본이 아닙니다.
async function* studyEvents() {
  yield { type: "text", text: "기록을 읽는 중" };
  yield { type: "text", text: "결과를 정리하는 중" };
  yield { type: "done", text: "완료" };
}

for await (const event of studyEvents()) {
  console.log(event.type, event.text);
}

실습 아이디어: 두 번째 이벤트 뒤에서 읽기를 멈추면 생산자 쪽 자원을 어떻게 정리해야 할지 생각해 보세요. followThreadEvents()의 try/finally와 unsubscribe()를 찾아 위 작은 예제에 필요한 정리 지점을 표시합니다.

PostgreSQL·Prisma: 데이터베이스는 협업 규칙도 맡는다

packages/db/prisma/schema.prisma의 Message는 [threadId, clientNonce]를 유일하게 유지합니다. Run은 [spaceId, clientNonce] 유일 제약과 [status, leaseExpiresAt] 인덱스를 가집니다. 앞의 제약은 중복 전송 구분에, 뒤의 인덱스는 실행 상태·만료 조건을 조회하는 경로에 대응합니다.

실습 아이디어: “같은 메시지 버튼을 두 번 눌렀다”와 “워커가 작업을 두 번 받았다”를 구분해 보세요. 전자는 전송 식별자, 후자는 실행 선점과 외부 효과 중복 방지가 중요합니다. 유일 제약 하나로 모든 중복 문제가 해결된다고 가정하지 않는 것이 학습 목표입니다.

메모리: 이름보다 저장과 검색의 구현을 확인한다

packages/memory/src/index.ts의 MarkdownMemoryStore는 기억을 memory_documents와 memory_revisions 테이블에 저장합니다. 이름에 Markdown이 있어도 기본 저장 위치가 개별 Markdown 파일이라는 뜻은 아닙니다. exportMarkdown()·importMarkdown()은 휴대 가능한 파일 형태의 경계입니다.

commit()은 현재 내용 갱신과 revision 추가를 Serializable 트랜잭션으로 묶고, expectedRevision이 주어졌으면 현재 번호를 비교합니다. withTransactionRetry()는 충돌한 트랜잭션을 다시 시도하는 경로입니다. 사용자가 오래된 버전을 기반으로 쓴 요청을 조용히 덮어쓰지 않도록 하는 장치를 배울 수 있습니다.

// MarkdownMemoryStore.commit()에서 발췌
if (request.expectedRevision !== undefined) {
  const live = existing?.revision ?? 0;
  if (live !== request.expectedRevision) {
    throw new Error(MEMORY_REVISION_CONFLICT_ERROR);
  }
}

기본 search()는 문서와 경로를 소문자로 바꾼 뒤 includes(q)로 찾고 점수는 1을 반환합니다. 벡터 임베딩을 계산하는 구현이 아닙니다. packages/adapter-kit/src/interfaces.ts의 SemanticMemoryProvider는 선택적인 의미 기억 기능을 별도 계약으로 정의합니다.

실습 아이디어: “자동차”가 있는 기억에서 “승용차”를 검색하는 경우를 예상해 보세요. 문자열 포함 검사만으로는 동의어를 자동으로 알아내지 못합니다. 이후 단어 검색·형태소 분석·임베딩 검색을 붙일 때 각 방식이 추가하는 비용과 이점을 비교하면 좋습니다.

React·다중 플랫폼: 공유할 것과 네이티브로 남길 것

apps/web/src/lib/rpc.ts는 RPCLink와 createORPCClient()로 클라이언트를 만듭니다. apps/web/src/pages/Shell.tsx는 그 클라이언트로 대화 이벤트를 구독합니다. 타입을 공유해도 화면이 열릴 때의 구독, 대상을 바꿀 때의 취소, 네트워크가 끊겼을 때의 복원은 별도 로직이 필요합니다.

packages/ui-tokens/src/index.ts는 공유 디자인 토큰의 출발점이고, 웹 컴포넌트는 packages/ui-web에 있습니다. 모바일에는 apps/mobile/app의 경로와 apps/mobile/lib의 기기별 처리가 따로 있습니다. 공유할 도메인 규칙과 플랫폼에 맡길 내비게이션을 구분하는 사례입니다.

실습 아이디어: “그룹 이름을 누르면 설정을 연다”는 동작에서 서버 계약을 바꿔야 하는 부분과 화면 이동만 바꾸면 되는 부분을 나눠 보세요. 커밋 8c65bc7의 제목도 모바일 그룹 채팅 제목에서 설정을 여는 변경을 가리킵니다. UI의 작은 변화가 시스템 전체의 변경을 요구하지 않게 만드는 경계를 찾아봅니다.

테스트 설계: 가짜 구현도 계약을 지켜야 한다

packages/adapters/src/scripted-runtime.ts의 ScriptedAgentRuntime은 실제 모델 대신 정해진 흐름을 내보냅니다. FakeSandboxProvider, 메모리 기반 작업 큐와 실시간 알림 구현도 있습니다. 이 조합으로 모델 호출 비용과 외부 장애를 줄인 채 상태 변화와 관찰 가능한 효과를 확인할 수 있습니다.

packages/adapters/src/sandbox-conformance.test.ts, packages/adapters/src/browser-conformance.test.ts, packages/adapters/src/secret-store-conformance.test.ts 같은 파일은 구현이 공통 계약을 따르는지 살피는 출발점입니다. 가짜가 통과했다고 모든 실제 제공자의 네트워크·권한·응답 특성까지 확인됐다고 볼 수는 없습니다.

새 기술을 하나씩 외우기보다, 경계 하나와 그 경계가 실패했을 때의 행동을 묶어서 공부하세요. 타입에는 잘못된 JSON을, 큐에는 중복 수신을, 스트림에는 재접속을, 메모리에는 동시 수정을 붙여 생각하면 코드가 요구사항으로 읽힙니다.

7하드웨어 / 시스템 요구사항

README에는 앱 전체를 위한 단일 최소 RAM·CPU 표가 없습니다. 코드 읽기, 외부 모델을 쓰는 서버, 로컬 컴퓨터 컨테이너, 로컬 모델 추론은 요구 자원이 다릅니다. 특히 모델 추론에 필요한 GPU 메모리를 웹 앱 자체의 요구사항과 섞으면 안 됩니다.

컴퓨터 한 대의 상한은 어디서 오는가

infra/sandboxes/supervisor/src/computer-spec.ts의 computerResourceLimits()가 Docker의 HostConfig에 들어갈 값을 계산합니다. parseMemoryBytes()는 g를 1024 ** 3으로 해석하므로 기본 2g는 2GiB입니다.

// infra/sandboxes/supervisor/src/computer-spec.ts의 기본값
const DEFAULT_COMPUTER_MEMORY = "2g";
const DEFAULT_COMPUTER_CPUS = "2";
const DEFAULT_COMPUTER_PIDS_LIMIT = "2048";

// computerResourceLimits()의 반환 값
return {
  Memory: memoryBytes,
  MemorySwap: memoryBytes,
  NanoCpus: nanoCpus,
  PidsLimit: pidsLimit,
};

MemorySwap을 Memory와 같은 값으로 설정하는 점이 눈에 띕니다. 소스 주석은 swap까지 포함한 상한이 예상보다 커지지 않게 하려는 의도를 설명합니다. 이 값들은 예약된 사용량이나 측정된 평균 사용량이 아니라 제한값입니다. 여러 봇이 컴퓨터를 공유할 수도 있으므로 봇 수와 컴퓨터 수를 그대로 같게 두면 안 됩니다.

한 컴퓨터의 자원 상한을 앱 전체의 최소 사양으로 읽지 않는 것이 용량 계획의 첫 단계입니다. PostgreSQL, API, 워커, 호스트 운영체제, 빌드 작업이 쓸 여유를 따로 남겨야 합니다.

학습용으로 잡아 볼 출발점

외부 모델을 사용하고 로컬 Docker 컴퓨터 한 대만 켜 보는 연습이라면 4코어·RAM 8GB 이상·여유 디스크 20GB 이상을 계획상의 출발점으로 잡을 수 있습니다. 이것은 공식 최소 사양이나 실측 보장이 아닌 교육용 추정입니다. 병렬 빌드·브라우저 탭·이미지 캐시가 늘면 RAM 16GB와 더 넓은 디스크가 유리할 수 있습니다.

별도의 GPU는 외부 모델 API를 호출하는 앱 서버의 필수 구성요소로 선언돼 있지 않습니다. packages/adapters/src/pi-local-provider.ts는 기본 로컬 주소를 http://127.0.0.1:11434/v1, 기본 문맥을 32_768, 최대 출력 토큰을 4_096으로 설정합니다. 이 값은 연결 설정의 기본값이며 해당 크기의 모델이 이미 설치됐거나 모든 모델이 이를 지원한다는 뜻은 아닙니다.

운영체제와 네트워크의 실전 조건

• 컨테이너: 게시 이미지 경로는 README와 이미지 게시 워크플로에서 linux/amd64·linux/arm64를 다룹니다. 호스트 OS 지원과 이미지 아키텍처는 구분해서 봅니다.
• 개발 포트: 웹 기본값은 5173, API 이미지 노출 포트에는 3100, supervisor 기본 포트는 7091이 있습니다. 내부 제어 포트를 곧바로 인터넷에 공개하는 구성이 아닙니다.
• 데이터베이스: 기본 Compose에서는 PostgreSQL이 내부 네트워크에 있습니다. 호스트 개발용 overlay는 loopback의 5433을 기본으로 내보냅니다.
• Docker 제어: supervisor는 Docker 소켓을 사용합니다. 그 소켓 접근 권한은 호스트 컨테이너 제어 권한과 연결되므로 일반 사용자용 HTTP API와 같은 경계로 취급하지 않습니다.
• 모바일 빌드: 소스에서 iOS·Android 앱을 빌드하는 일에는 해당 플랫폼의 개발 도구가 추가됩니다. 웹 학습을 위해 두 네이티브 빌드 환경을 모두 준비할 필요는 없습니다.

8직접 해볼 수 있는 실습 과제

처음 두 과제는 앱을 설치하지 않고 할 수 있습니다. 구현을 실험할 때는 별도의 개인 학습용 코드나 브랜치를 쓰고, 저장소의 전체 실행 흐름을 한꺼번에 올리기보다 작은 경계부터 다루세요. 아래 명령은 독자가 준비된 환경에서 선택할 수 있는 예시입니다.

# 저장소 루트에서 실행할 수 있는 읽기 전용 검색 예시
rg -n 'sendThreadMessage|enqueueRunsNeedingContinue' apps/api/src
rg -n 'runContinueJob|continueRun' packages/adapter-kit/src packages/adapters/src
rg -n 'clientNonce|leaseFence' packages/db/prisma/schema.prisma

이미 의존성이 준비된 환경에서는 pnpm exec vitest run packages/core/src/run-state.test.ts로 해당 규칙의 테스트를 확인할 수 있습니다. 이 테스트에는 fast-check로 여러 입력 조합을 생성해 종료 상태의 전이를 확인하는 사례도 있습니다.

// 개념 실습용 독립 예제: 입력과 기대 결과를 명시합니다.
const events = Array.from({ length: 10 }, (_, i) => ({ seq: i + 1 }));
const readAfter = (cursor: number) => events.filter((e) => e.seq > cursor);

const resumed = readAfter(4).map((e) => e.seq);
// 기대 결과: [5, 6, 7, 8, 9, 10]

실습의 완료 기준은 화면이 한 번 잘 뜨는 것이 아니라, 정해 둔 실패 상황에서도 설명한 규칙이 유지되는 것입니다. 실패를 일부러 만들 수 있어야 복구 코드가 왜 필요한지 이해할 수 있습니다.

9관련 기술 심화 학습 로드맵

주당 4~6시간을 가정한 학습 제안입니다. JavaScript의 함수·객체·배열과 기본적인 async/await를 먼저 알아두면 좋습니다. 일정은 제품의 공식 교육 과정이 아니며, 낯선 개념이 많으면 한 주를 두 주로 늘려도 됩니다.

그다음에는 관심 분야로 갈라지기

• 백엔드: 조건부 갱신, 트랜잭션 격리, 연결 풀, advisory lock, 외부 효과의 멱등성 순서로 확장합니다.
• 프론트엔드: 이벤트를 화면 상태로 투영하기, 구독 해제, 재접속, 로딩·사용자 대기 표현, 접근성을 살펴봅니다.
• 에이전트: 모델 호출과 도구 호출의 경계, 호출 예산, 취소, 문맥 압축, 제공자 오류 변환을 추적합니다.
• 인프라: 최소 권한 DB 계정, 컨테이너 제어 권한, 저장 데이터·키 백업, 이미지 버전 고정과 복구 절차를 학습합니다.
• 다중 플랫폼: 공유 계약과 디자인 토큰을 유지하면서 네이티브 이동·권한·저장을 분리하는 기준을 정리합니다.

packages/adapters/src/pi-runtime.ts의 maxToolCallsPerTurn()는 에이전트 운영을 더 공부할 좋은 출발점입니다. MAX_TOOL_CALLS_PER_TURN이 비어 있거나 0이면 기본적으로 무제한을 뜻합니다. 제한값이 존재하는지와 기본으로 제한되는지는 다른 질문입니다.

학습 범위를 넓힐 때마다 정상 동작 하나와 실패 시나리오 하나를 짝지으면 설계 판단이 쌓입니다. 예를 들어 “새 제공자 연결” 다음에는 “키가 없는 제공자”, “구독 성공” 다음에는 “인증이 취소된 열린 구독”을 놓고 읽습니다.

10핵심 키워드 사전

같은 단어라도 범위를 확인하세요. “활성 실행”과 “CPU를 쓰는 실행”, “기억”과 “벡터 검색”, “실시간”과 “기록의 영속성”, “컨테이너”와 “절대적인 보안 경계”는 각각 별도의 성질입니다. 타입·필드·조건문으로 그 차이를 확인하는 습관이 중요합니다.

11참고 링크

공식 저장소·설정·운영 문서

• 공식 저장소 · 분석 기준 README · 기준 커밋
• v0.3.3 릴리스 · Apache-2.0 라이선스 원문
• 루트 의존성·실행 명령 · 워크스페이스 범위 · 빌드 작업 그래프
• 자체 호스팅 가이드 · 컴퓨터 제공자 가이드
• 컴퓨터 런타임 문서 · 저장 데이터 암호화 문서
• CI 구성 · 앱 이미지 구성 · 컴퓨터 이미지 구성

핵심 분석을 다시 따라갈 소스

• 런타임·컴퓨터·메모리·작업 계약 · 워커 구성 루트
• 메시지 접수와 재전송 처리 · 실행 선점·도구 처리·재개
• 실행 상태 전이 · 누락 실행과 오래된 잠금의 재조정
• 이벤트 저장·이어받기 · PostgreSQL 알림 구현
• 기본 기억 저장·검색·수정 충돌 · 공간별 데이터 접근 문맥
• 도구 승인 정책 · 컴퓨터 자원·격리 설정

관련 기술의 공식 학습 자료

• TypeScript 핸드북 · Zod 문서 · oRPC 문서
• Hono 문서 · Prisma 문서 · Better Auth 문서
• PostgreSQL 16 트랜잭션 격리 · NOTIFY · 행 수준 보안
• Graphile Worker 문서 · Docker Compose 문서
• React 학습 자료 · Electron 문서 · Expo 문서 · Astro 문서
• Vitest 가이드 · Playwright 문서 · MCP 입문 문서

외부 기술 문서는 독립적으로 갱신됩니다. 이 글의 버전 표는 저장소의 선언값이고, 공식 문서의 기본 화면은 다른 최신 버전을 설명할 수 있습니다. API를 따라 구현할 때에는 패키지 버전과 해당 문서 버전을 함께 확인하세요.

현재 상태 (2026-10-23 확인)

줄 수 집계의 재현 기준

줄 수는 git ls-files -z의 추적 파일 목록을 확장자별로 분류한 물리적 줄 수입니다. 마지막 개행이 없는 비어 있지 않은 파일도 마지막 한 줄을 포함합니다. JavaScript에는 .js·.mjs·.cjs를 합산하며, TypeScript에는 .d.ts가 포함됩니다. JSON·YAML·lockfile·Markdown·이미지는 위 언어별 집계에서 제외합니다.

집계한 표의 언어·형식만 합치면 570,478줄입니다. 이는 GitHub의 언어 비율 산정이나 주석을 뺀 유효 코드 줄 수와 다릅니다. 많은 테스트 코드가 있는 대형 제품이라는 독해 난이도의 참고값으로 사용하세요.