데몬과 런타임

Multica는 실행을 기록하고 조율하며 연결된 컴퓨터가 실행을 담당합니다. 컴퓨터의 데몬(daemon)이 실행을 가져간 뒤 로컬에 설치된 AI 코딩 도구를 호출합니다.

Qoder Cloud Agent 원격 런타임

Qoder Cloud Agent는 할당된 태스크를 원격 세션으로 실행합니다. Multica 서버가 기존 데몬 프로토콜을 사용하는 브리지를 관리하므로 사용자가 로컬 데몬을 실행할 필요가 없습니다.

시작하기 전에

• 워크스페이스 관리자 권한이 필요합니다. Qoder 연결은 워크스페이스마다 하나입니다.
• Qoder에서 개인 액세스 토큰(PAT), 하나 이상의 실행 환경, 사용할 QCA 에이전트를 만드세요. 모델, 도구, 스킬은 Multica가 아니라 Qoder의 QCA 에이전트에서 설정합니다.
• 셀프 호스팅에서는 서버에 MULTICA_VCS_SECRET_KEY(base64로 인코딩한 32바이트 키, 재시작해도 같은 값 유지)를 설정해야 합니다. 설정하지 않으면 추가 메뉴에 Qoder Cloud Agent가 나타나지 않습니다.

Qoder 연결하기

1. 런타임 페이지에서 추가를 클릭하고 클라우드 서비스 아래의 Qoder Cloud Agent를 선택합니다.
2. 리전에서 PAT를 발급한 사이트를 고릅니다: 글로벌(qoder.com) 또는 중국(qoder.com.cn). PAT는 발급한 사이트에서만 동작합니다. 거부되면 다른 사이트로 다시 시도하는 버튼을 사용하세요.
3. 개인 액세스 토큰에 PAT를 붙여 넣습니다. 확인이 끝나면 Qoder에서 실행 환경 목록을 불러옵니다. 환경이 하나뿐이면 자동으로 선택되고, 여러 개면 직접 선택합니다.
4. 선택 사항: GitHub authorization을 열고 에이전트가 클론할 저장소마다 URL과 토큰을 추가합니다. 에이전트는 여기서 승인한 저장소만 클론할 수 있습니다.
5. 선택 사항: 실행 설정을 열어 동시 실행 수(기본 3, 최대 10)와 실행 제한 시간(기본 60분, 5~240분)을 설정합니다.
6. 연결을 클릭합니다. Qoder Cloud Agent가 런타임 페이지의 클라우드 영역에 나타나고 몇 초 안에 온라인이 됩니다.

에이전트 추가하기

런타임 페이지에서 Qoder Cloud Agent를 열고 이것으로 에이전트 만들기를 클릭합니다. 평소처럼 에이전트를 만들면서 Qoder 런타임을 선택해도 됩니다. 에이전트 양식의 QCA 에이전트에서 원격 에이전트를 선택하세요. 기존 에이전트는 라우팅 탭에서 QCA 에이전트나 기본 저장소를 바꿀 수 있습니다. 여러 Multica 에이전트가 하나의 연결을 공유하면서 각각 다른 QCA 에이전트에 연결될 수 있습니다.

자격 증명은 암호화되어 워크스페이스 내에서 공유됩니다. 관리자가 연결을 관리하고, 멤버는 접근 가능한 QCA 에이전트를 선택할 수 있습니다. 저장소와 시작 브랜치는 프로젝트에서 선택하며, 해당 저장소의 토큰은 QCA 세션 생성 시 전달됩니다. 저장된 PAT는 브라우저로 다시 반환되지 않습니다.

관리자는 Qoder Cloud Agent 페이지에서 연결과 저장소를 편집할 수 있습니다. 일시 중지는 자격 증명과 에이전트를 유지한 채 새 태스크 전송을 멈추고, 연결 해제는 저장된 토큰을 삭제하고 런타임을 제거하며 에이전트 연결을 해제합니다.

실행 방식

동시 실행 한도를 넘는 태스크는 대기열에서 기다립니다. 같은 태스크의 후속 실행은 이전 세션이 유휴 상태이면 해당 Qoder 세션을 이어서 사용합니다. 에이전트에 기본 저장소를 설정할 수 있으며, 태스크의 프로젝트에 저장소가 없을 때 사용됩니다. 에이전트는 태스크 식별자가 포함된 브랜치 이름과 식별자로 시작하는 PR 제목을 사용하도록 안내받으므로 PR이 태스크에 자동으로 연결됩니다.

초기 버전은 태스크 실행, 진행 상황 동기화, 취소, 영구 실행 기록을 통한 복구를 지원합니다. 채팅, 로컬 디렉터리, 첨부 파일, 원격 QCA Agent 생성은 지원하지 않습니다. 자세한 내용은 README를 참고하세요.

개념 구분

• 데몬은 한 컴퓨터에서 실행되는 Multica 백그라운드 프로그램입니다. 서버 연결, 로컬 도구 검색, 실행 수령, 결과 반환을 담당합니다.
• 런타임은 워크스페이스가 사용할 수 있는 구체적인 실행 환경을 나타냅니다. 컴퓨터 한 대와 그 컴퓨터의 AI 코딩 도구 하나 또는 사용자 지정 런타임 설정의 조합입니다.

예를 들어 한 컴퓨터에 Claude Code와 Codex가 모두 설치되어 있고 두 워크스페이스에 연결되어 있다면 데몬이 각 워크스페이스에 Claude Code와 Codex 런타임을 각각 등록합니다. 데몬을 다시 시작하면 기존 기록이 업데이트되며 같은 조합의 런타임이 계속 새로 생기지 않습니다.

실행 위치와 데이터 경계

로컬 런타임이 호출하는 AI 코딩 도구, 도구 자체의 로그인 자격 증명, 로컬 코드 디렉터리는 연결된 컴퓨터에 남습니다. Multica 서버가 로컬 도구를 대신해 명령을 실행하거나 전체 작업 디렉터리를 자동으로 업로드하지 않습니다.

팀 협업을 위해 서버에는 태스크, 댓글, 에이전트 설정, 실행 컨텍스트, 실행 기록, 에이전트가 반환한 결과가 저장됩니다. 이 내용에는 에이전트가 직접 읽고 답변에 포함한 코드 조각이나 다른 프로젝트 컨텍스트가 들어갈 수 있습니다.

데몬 시작

Multica Desktop을 사용하면 앱이 데몬을 자동으로 시작하므로 별도 명령을 실행할 필요가 없습니다.

Web, 원격 컴퓨터, 화면 없는 환경에서는 먼저 Multica CLI를 설치한 뒤 다음을 실행합니다.

multica daemon start

데몬은 기본적으로 백그라운드에서 실행됩니다. 자주 사용하는 명령은 다음과 같습니다.

실행용 작업 디렉터리를 다른 디스크에 두려면 multica config set workspaces_root <path>로 현재 profile의 루트를 저장하거나 daemon start 또는 daemon restart에 --workspaces-root <path>를 전달합니다. flag는 MULTICA_WORKSPACES_ROOT보다 우선하고, 환경 변수는 profile 설정보다 우선합니다. 루트를 변경해도 기존 작업 디렉터리는 이동되지 않습니다.

시작할 때 데몬은 PATH에서 지원되는 AI 코딩 도구를 감지하고 사용자가 연결할 권한이 있는 워크스페이스에 런타임을 등록합니다. 도구를 방금 설치하거나 로그인했다면 데몬을 다시 시작해 다시 감지할 수 있습니다.

데몬을 시작하려면 기본 지원 AI 코딩 도구를 하나 이상 감지해야 합니다. 설치 방법과 실행 파일 이름은 AI 코딩 도구 설치를 참고하세요.

디스패치와 온라인 상태

런타임이 등록되면 연결을 계속 유지합니다. 새 실행이 큐에 들어오면 서버가 해당 데몬에 알리고, 연결이 끊겼을 때를 대비해 데몬도 주기적으로 폴링합니다. 따라서 런타임이 온라인이고 여유 용량이 있으면 실행은 보통 즉시 시작됩니다.

데몬은 15초마다 heartbeat를 보냅니다. 서버는 heartbeat와 연결 상태를 함께 사용해 런타임의 온라인 여부를 판단합니다. 데몬이 예기치 않게 종료되면 보통 늦어도 약 3분 안에 오프라인으로 표시됩니다.

런타임이 오프라인일 때는 다음과 같이 처리됩니다.

• 이미 큐에 들어간 실행은 런타임이 복구될 때까지 기다립니다. 해당 런타임이 재연결 유예를 넘겨 하트비트를 멈추고 동시에 실행 자체도 그만큼 기다린 뒤에만 실패하므로, 단지 바쁜 런타임은 밀린 실행을 그대로 유지하고 이미 오프라인인 런타임에 배정된 실행도 온전한 유예를 한 번 갖습니다.
• 진행 중이던 실행은 실패합니다. 조건을 만족하는 태스크 또는 대화 실행은 자동으로 재시도될 수 있습니다.
• 데몬이 다시 시작되면 런타임을 재등록하고 이전에 정상적으로 끝나지 않은 실행을 회수합니다.
• 7일 넘게 오프라인이고 연결된 에이전트가 하나도 없는 런타임은 보관된 에이전트까지 확인한 뒤 자동으로 정리됩니다.

자세한 상태와 재시도 규칙은 실행을 참고하세요.

동시 실행 제한

데몬 한 대는 기본적으로 실행을 최대 20개까지 동시에 처리하며, 에이전트 한 명은 기본적으로 최대 6개까지 처리합니다. 실제 동시 실행 수에는 둘 중 더 작은 값이 적용됩니다.

상한에 도달하면 새 실행은 계속 큐에서 기다립니다. 에이전트 설정에서 개별 에이전트의 동시 실행 수를 조정할 수 있고 MULTICA_DAEMON_MAX_CONCURRENT_TASKS로 컴퓨터 전체 상한을 조정할 수도 있습니다. 병렬 실행은 컴퓨터 성능, 도구 계정 사용량, 같은 작업 디렉터리를 동시에 사용합니다.

비공개와 공개

로컬 런타임의 기본값은 비공개입니다. 그 위에 에이전트를 만들 수 있는 사람은 런타임 owner뿐이며, 워크스페이스 owner와 admin도 예외가 아닙니다. 런타임은 다른 멤버의 컴퓨터이고, 거기서 에이전트를 실행하면 그 멤버의 컴퓨터와 도구 자격 증명을 사용하게 되기 때문입니다.

공개로 바꿀 수 있는 사람은 런타임 owner뿐입니다. 워크스페이스 관리자는 런타임의 이름을 바꾸거나 삭제할 수 있지만, 공유 여부는 owner가 결정합니다. 공개하면 워크스페이스의 다른 멤버도 이 런타임을 선택할 수 있습니다. 기반 AI 코딩 도구의 로그인 자격 증명을 공유하는 것이 아니라 멤버가 에이전트 실행을 해당 컴퓨터로 라우팅할 수 있게 하는 것입니다.

소유자가 공개 런타임을 다시 비공개로 전환하면 Multica는 에이전트 빌더 세션을 포함하여 영향을 받는 에이전트와 활성 실행을 표시합니다. 확인하면 다른 멤버의 해당 에이전트 연결을 해제하고, 대기 중·배포됨·실행 중·로컬 디렉터리 대기·지연 중인 실행을 runtime_access_revoked로 취소합니다. 해당 에이전트에 할당된 활성 자동화도 일시 중지합니다. 소유자 자신의 에이전트와 실행에는 영향을 주지 않습니다. 대상이 바뀌면 다시 확인해야 하며, 채팅이 동시에 변경되는 경우 재시도가 필요할 수 있습니다. 작업을 재개하려면 에이전트를 사용 가능한 런타임에 연결한 후 일시 중지된 자동화를 직접 재개하세요.

취소해도 채팅 기록은 유지되며 초안·첨부 파일 복원 데이터는 서버에 저장됩니다. 웹과 데스크톱은 기존 초안 복원 UI를 사용하지만 모바일에는 아직 해당 UI가 없습니다. 이미 시작했지만 출력이 없는 실행은 데몬의 취소 확인 또는 서버의 유예 기간 종료 후 입력 복원 여부를 결정합니다. 연결된 데몬은 일반 확인 과정에서 취소를 받습니다. 오프라인에서도 서버의 접근 권한은 즉시 취소되지만, 로컬 프로세스는 다시 연결되어 취소를 받을 때까지 계속될 수 있으므로 즉시 원격 중단을 보장할 수 없습니다.

사용자 지정 런타임 설정

팀에서 내부 wrapper, 고정 버전 실행 파일을 사용하거나 호환 도구에 고정 인수를 추가해야 한다면 사용자 지정 런타임 설정을 만들 수 있습니다.

사용자 지정 설정이 새 통신 프로토콜을 추가하지는 않습니다. 만들 때 Multica가 이미 지원하는 프로토콜 계열 중 하나를 선택해야 하며(도구 연동 프로토콜 유형은 AI 코딩 도구 비교 참고), 명령 자체도 해당 프로토콜과 호환되어야 합니다.

작업 런타임 환경

데몬이 에이전트 작업을 시작하면 작업 컨텍스트를 런타임 프로세스에 주입합니다. 이 값은 데몬이 관리하므로 에이전트의 사용자 지정 환경에서 MULTICA_ 변수나 작업 임시 디렉터리 변수를 덮어쓸 수 없습니다.

다음 표는 사용자 지정 런타임이 현재 사용할 수 있는 변수를 보여 줍니다. 전체 목록이 아니며 버전이 보장되는 API도 아닙니다. 연동에는 연동 계약으로 표시된 5개 변수만 사용하세요. 나머지는 참고 정보이며 변경될 수 있습니다.

MULTICA_TOKEN을 사용하는 요청의 작성자는 서버가 결정하며, 태스크 댓글 같은 쓰기는 할당된 에이전트와 실행 중인 작업에 귀속됩니다. 자격 증명의 전체 바인딩, 권한, 귀속, 최대 24시간의 유효 기간 및 정리 동작은 에이전트 실행용 임시 토큰을 참고하세요.

설정 만들기

워크스페이스 owner와 admin만 사용자 지정 런타임 설정을 만들고 수정하거나 삭제할 수 있습니다.

1. 런타임을 열고 해당 명령이 설치된 컴퓨터로 들어갑니다.
2. 사용자 지정 런타임 추가를 클릭합니다.
3. 명령이 실제로 호환되는 프로토콜 계열을 선택합니다.
4. 이름, 명령, 고정 인수를 입력하고 저장합니다.

설정은 워크스페이스에서 공유됩니다. 연결된 각 컴퓨터가 이 명령을 개별적으로 찾으며 PATH에서 명령을 확인할 수 있는 컴퓨터만 해당 런타임을 등록합니다. 설정을 만든다고 명령이 자동으로 설치되거나 다른 멤버의 도구 로그인이 완료되지는 않습니다.

여기에는 shell script가 아니라 실행 파일과 인수를 입력합니다. 일반 인수, 따옴표, 백슬래시 이스케이프는 사용할 수 있지만 파이프, 리디렉션, &&, ;, 역따옴표, 환경 변수 확장은 사용할 수 없습니다. 이런 동작이 필요하면 wrapper script에 넣고 해당 스크립트를 명령으로 입력하세요.

Desktop이 시작한 데몬에서 터미널에서는 실행되는 명령을 찾지 못한다면 현재 컴퓨터에 절대 경로를 설정할 수 있습니다.

multica runtime profile set-path <profile-id> --path /absolute/path/to/command

경로 덮어쓰기를 제거하려면 다음을 실행합니다.

multica runtime profile unset-path <profile-id>

설정 변경은 이후 가져가는 실행에만 적용됩니다. 설정을 삭제하기 전에 해당 런타임에 계속 연결된 활성 에이전트를 먼저 처리해야 합니다. 특정 컴퓨터의 런타임 인스턴스만 삭제해도 설정은 삭제되지 않으며 실행 중인 데몬이 다시 등록합니다.

런타임 오프라인 문제 해결

다음 순서로 확인하세요.

1. multica daemon status를 실행해 데몬이 시작되었는지 확인합니다.
2. multica daemon logs -f를 실행해 로그인, 네트워크, 도구 감지 오류를 확인합니다.
3. 같은 실행 환경에서 command -v <도구 명령>을 실행해 데몬이 도구를 찾을 수 있는지 확인합니다.
4. Multica의 런타임 페이지를 열고 대상 컴퓨터와 해당 AI 코딩 도구가 온라인으로 표시되는지 확인합니다.
5. 도구를 방금 설치했거나 경로 또는 설정을 변경했다면 multica daemon restart를 실행합니다.

그래도 해결되지 않으면 문제 해결을 참고하세요.

다음 단계

• AI 코딩 도구 설치 — 지원되는 AI 코딩 도구를 설치하고 확인합니다.
• AI 코딩 도구 비교 — 모델, 세션 복원, MCP, 스킬 지원을 비교합니다.
• 실행 — 큐 대기, 중지, 재시도를 알아봅니다.