AI 코딩 에이전트에 관한 대화는 결국 언제나 같은 실용적인 질문에 도달합니다. 대개는 좀 더 일찍 했어야 할 질문이죠. 바로 코드가 실제로 어디에서 실행되는가입니다. 어떤 모델을 쓰는지가 아니라, 여러분의 리포지토리와 자격 증명, 캐시, 그리고 에이전트가 명령을 입력하는 셸을 어느 머신이 들고 있는가 하는 문제입니다.
Sharkly는 이 답을 Computer라는 일급 개념으로 만듭니다. Computer는 Agent 작업을 위한 실행 호스트를 제공합니다. 로컬 컴퓨터, 원격 서버, 컨테이너, 또는 지원되는 클라우드 호스트가 될 수 있습니다. 여러분의 노트북도 해당됩니다. 랙에 있는 리눅스 장비도 마찬가지고요. 호스트는 여러분이 선택하고 여러분이 통제하며, Sharkly는 보이지 않는 어딘가에서 코드를 실행하는 대신 그 호스트로 작업을 조율합니다.
Sharkly는 Claude Code, Codex 또는 다른 실행 도구를 대체하는 것이 아닙니다. 팀이 이미 사용하는 도구 주위에 공유 Task, Computer, 컨텍스트, 제어, 리뷰 계층을 더합니다. 그 도구들은 여러분의 머신에 그대로 설치된 채 남고, 모델 사용은 도구에 설정된 구독이나 API 키를 통해 계속 이어집니다.
TL;DR
Computer는 Sharkly에서 Agent 작업을 위한 실행 호스트입니다. 즉 여러분이 통제하는 로컬 컴퓨터, 원격 서버, 컨테이너, 또는 지원되는 클라우드 호스트입니다. 작은 로컬 서비스가 Computer를 Sharkly에 연결하고, 사용 가능한 Runtime(해당 호스트에 설치된 구체적인 에이전트 도구, 예를 들어 Claude Code나 Codex)을 감지하고, 대기 중인 실행을 받아 작업 디렉터리를 준비하고, 선택된 Runtime을 시작한 뒤 진행 상황을 Task로 스트리밍합니다. 개인 머신은 Sharkly Desktop으로, 원격 호스트는 Sharkly CLI와 일회용 설치 토큰으로 연결하세요. 모델 사용은 도구에 이미 설정된 구독과 API 키를 통해 이루어지고, 동시성 한도가 호스트 하나가 감당할 병렬 작업량을 결정합니다.
Computer란 무엇이고, 무엇이 아닌가
Sharkly는 실행을 네 가지 역할로 나누며, 각 역할은 정확히 하나의 임무만 맡습니다.
- Agent는 작업을 어떻게 처리할지 정의합니다. 지침, Skills, 리포지토리, 실행 설정이 여기에 해당합니다.
- Computer는 호스트와 로컬 리소스를 제공합니다. OS, 파일, 자격 증명, 네트워크, 도구입니다.
- Runtime은 실제 에이전트 세션을 수행합니다. 해당 Computer에서 감지된 코딩 도구입니다.
- Task는 공유 기록으로 남습니다. 목표, 논의, 실행 상태, 트레이스, 결과입니다.
이 분리가 이후 내용의 대부분을 설명해 줍니다. Agent는 실행 호스트가 아닙니다. 같은 Agent 구성이 시간이 지나면서 다른 Computer를 가리킬 수 있습니다. Computer는 에이전트가 아닙니다. 하나 이상의 Runtime을 보유하고, 작업이 배정되기 전까지는 아무것도 하지 않습니다. 그리고 Computer 하나가 동시성 한도 내에서 여러 Agent를 동시에 지원할 수 있습니다.
이 구조는 Sharkly의 제안을 설명하기도 합니다. 호스팅 플랫폼은 모델과 러너, 인프라를 하나의 제품으로 묶습니다. 즉 여러분의 코드가 여러분이 운영하지 않는 인프라에서 실행된다는 뜻입니다. Sharkly는 다른 입장을 취합니다. 실행 호스트는 여러분의 것이고, Sharkly가 그 위에 더하는 것은 할당, 큐잉, 리뷰입니다. 이 모델이 처음이라면 Sharkly란 무엇인가에서 전체 그림을 확인할 수 있습니다.
로컬 서비스: 실제 작업을 수행하는 구성 요소
작은 로컬 서비스가 각 Computer를 Sharkly에 연결합니다. Computer를 등록하고, 설치된 Runtime을 감지하고, 하트비트를 보내고, 대기 중인 실행을 받아 작업 디렉터리를 준비하고, 선택된 에이전트 도구를 시작한 뒤 진행 상황과 결과를 다시 보고합니다.
설계상의 한 가지 세부 사항이 운영 측면에서 큰 비중을 차지합니다. 로컬 서비스가 서버로의 연결을 시작하므로 일반적인 구성에서는 인바운드 포트가 필요하지 않습니다. 덕분에 가정용 공유기 뒤의 노트북, 기업 방화벽 뒤의 워크스테이션, 프라이빗 서브넷의 서버가 모두 똑같이 훌륭한 Computer가 될 수 있습니다.
Sharkly가 Computer의 생존을 확인하는 방법은 하트비트입니다. 서버가 하트비트를 받고 있으면 Online, 멈추면 Offline입니다. 문제 해결 시간을 아껴 주는 경계가 있습니다. 온라인이라는 것은 하트비트가 도착하고 있다는 뜻일 뿐이며, 선택한 Runtime이 Task를 실행할 수 있다는 뜻은 아닙니다.
Runtime: Computer가 실제로 실행할 수 있는 것
Runtime은 Computer에서 감지된, 지원되는 에이전트 실행 기능입니다. 로컬 서비스가 지원되는 에이전트 도구를 스캔해 사용 가능한 각 도구를 보고하므로, Claude Code와 Codex가 설치된 Computer는 둘 다 Agent가 선택할 수 있는 Runtime으로 노출합니다.
Computer 상세 페이지에서는 각 Runtime의 기능 상태를 보여 줍니다.
- Available: Runtime이 연결되어 있고 Agent 작업을 실행할 수 있습니다.
- Needs configuration: 도구는 감지되었지만 필요한 구성이 누락되어 있습니다.
- Not installed: 로컬 서비스가 도구를 사용할 수 없습니다. 설치하거나 다른 Runtime을 선택하세요.
- Unsupported: Runtime 또는 환경이 지원되는 기능 범위를 벗어났습니다.
설치 책임은 의도적으로 여러분에게 남아 있습니다. 각 도구를 직접 사용할 때와 같은 방식으로 설치하고 인증하면 됩니다. Computer 상세 페이지에 공식 설치 가이드 링크가 있고, 다시 스캔하면 로컬 서비스가 도구를 인식하는지 확인할 수 있습니다. 의존하는 기능이 감지되지 않으면 이름과 시작 명령을 지정해 커스텀 ACP Runtime을 추가한 뒤 연결을 테스트할 수 있습니다.
여기서 두 가지 결과가 따라옵니다. '구독 직접 가져오기'라는 표현은 문자 그대로입니다. 모델 할당량은 팀이 연결한 AI 코딩 도구, 요금제, API 계정에 달려 있으므로, 할당량 오류는 Sharkly 설정이 아니라 도구에 구성된 계정을 가리킵니다. 그리고 모델 선택은 도구에 속합니다. Agent는 자신의 Runtime 기본 모델을 따릅니다. Agent 구성 방법은 Sharkly의 Agents에서 다룹니다.
첫 번째 Computer 연결하기
첫 번째 Computer는 보통 지금 앉아 있는 머신입니다. Settings를 열고 Computers로 이동한 뒤 Connect Computer를 선택하고, 사용 중인 운영체제에 맞는 설정 경로를 고르세요. 지원되는 개인 컴퓨터라면 권장 경로는 Sharkly Desktop 설치입니다. 로컬 서비스가 함께 포함되어 있고 등록 과정을 안내해 줍니다. 시작 가이드를 따르면 약 10분 만에 처음부터 끝까지 진행할 수 있습니다.
연결한 뒤에는 최소 하나의 Runtime이 Available로 표시되는지 확인하세요. 많은 사람이 건너뛰는 확인 지점입니다. 사용 가능한 Runtime이 없는 연결된 Computer는 Agent 작업을 실행할 수 없습니다.
노트북과 관련해 중요한 데스크톱 전용 설정이 두 가지 있습니다. Prevent sleep은 장시간 실행이 중단되지 않도록 머신을 깨어 있게 유지하고, Keep running with lid closed는 macOS에서 별도로 제공되는 옵션입니다. 둘 다 로컬 머신에서만 나타나며 원격 Computer에서는 절대 표시되지 않습니다.
원격 서버 추가하기
노트북은 첫 번째 Computer로는 훌륭하지만 영구적인 Computer로는 부적합합니다. 잠자기 상태에 들어가고, 이동하고, IDE와 메모리를 두고 경쟁합니다. 자연스러운 다음 단계는 계속 켜져 있는 원격 호스트입니다. 여기에 Sharkly CLI와 로컬 서비스를 직접 설치하세요.
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
sharkly version
그다음 Computers 페이지에서 일회용 설치 토큰을 생성하고, 안내되는 등록 명령을 대상 호스트에서 실행하세요.
sharkly computer register --install-token sit_...
등록은 조직에 Computer를 기록하고, 로컬 서비스를 시작하며, Runtime 감지를 시작합니다. 설치 토큰은 30분 후 만료되고 일회용이므로, 문서에서 명확히 밝히는 위생 규칙이 따라옵니다. 재사용 가능한 이미지, 스크립트, Task, 댓글에 토큰을 넣지 마세요.
여기서는 자격 증명이 의도적으로 분리되어 있습니다. 개인 액세스 토큰은 컴퓨터를 등록하지 않고, 설치 토큰은 사람이 사용하는 CLI 로그인을 만들지 않습니다. shk_ 개인 액세스 토큰은 sharkly task list 같은 리소스 명령에 대한 인증을 담당하고, sit_ 설치 토큰은 로컬 서비스가 사용하는 세션을 생성합니다. 더 넓은 명령 범위는 Sharkly CLI 및 API 가이드에서 다룹니다.
등록 후에는 같은 CLI가 진단 도구 역할도 합니다. sharkly computer status와 sharkly computer logs는 호스트의 로컬 상태를 읽고, sharkly computer list, show, usage, ping은 어디서든 등록된 Computer를 조회합니다. 원격 호스트에도 노트북과 같은 것들이 필요합니다. 에이전트 도구를 설치하고 인증하고, 프라이빗 리포지토리를 위한 Git 접근을 준비해야 합니다.
로컬, 원격, 컨테이너: 솔직한 비교
정답인 호스트는 하나가 아닙니다. 문서는 이들 모두를 Computer로 취급하며, 트레이드오프는 일반적인 인프라 수준의 것들입니다.
| 호스트 | 적합한 용도 | 장점 | 주의할 점 |
|---|---|---|---|
| 로컬 컴퓨터(Sharkly Desktop) | 첫 설정, 개인 작업, 기존 체크아웃과 캐시를 재사용하는 Specified 디렉터리 실행 | 추가 인프라가 전혀 필요 없음, 정확히 여러분의 환경과 자격 증명을 그대로 사용, Specified 작업 디렉터리는 로컬 Computer에서만 사용 가능 | 잠자기와 종료가 가용성을 끊음, 실행이 여러분의 작업과 CPU·메모리를 두고 경쟁 |
| 원격 서버(CLI + 로컬 서비스) | 팀 워크로드, 상시 가동 용량, 더 높은 동시성 | 계속 온라인 유지, 에이전트 부하를 누구의 노트북과도 분리, 호스트 하나로 여러 Agent 지원 가능 | Runtime과 Git 접근을 직접 설치·인증해야 함, 용량 계획도 직접 수립 |
| 컨테이너 또는 지원되는 클라우드 호스트 | 재현 가능하고 폐기 가능한 실행 환경 | 깨끗하게 재구축 가능한 환경, 설치 토큰을 통한 동일한 등록 절차 | 일회용 토큰은 등록할 때마다 생성해야 하며, 재사용 가능한 이미지에 넣어서는 안 됨 |
가장 중요한 판단 기준은 두 가지입니다. 이미 신뢰하는 환경에서 Agent가 작업하기를 원하면 로컬 Computer를 사용하고, 노트북을 닫아 둔 동안에도 Task가 계속 흘러가야 한다면 원격 Computer를 사용하세요. 작업을 다른 호스트로 라우팅하는 것은 워크플로 변경이 아니라 구성 변경이므로, 많은 팀이 결국 둘 다 갖추게 됩니다.
실행 중에 일어나는 일
Agent에 할당된 Task가 준비되면 Sharkly는 실행을 큐에 넣고 선택된 Computer로 디스패치합니다. Runtime이 시작되기 전에 로컬 서비스는 동시성 여유를 기다리고, 디렉터리를 준비하고, 리포지토리를 가져오고, 허용된 환경 변수를 주입할 수 있습니다.
디렉터리 준비는 두 가지 모드 중 하나를 따릅니다. Temporary 모드에서는 각 Task가 격리된 디렉터리를 받고, 리포지토리 기반 실행은 캐시된 리포지토리 데이터로 새 Git 워크트리를 준비할 수 있습니다. 대부분의 리포지토리 작업과 여러 Task가 같은 코드베이스를 병렬로 수정할 가능성이 있을 때 사용하세요. 이 내용은 Sharkly가 병합 충돌 없이 Agent를 병렬로 실행하는 방법에서 자세히 다룹니다. Specified 모드에서는 로컬 Computer에 구성된 절대 경로 디렉터리 하나를 그 안의 의존성과 캐시와 함께 재사용하며, 지정된 디렉터리 하나는 한 번에 하나의 실행만 처리합니다.
Runtime이 작업하는 동안 진행 상황이 스트리밍됩니다. 실행 상태는 Queued, Dispatched, Waiting for local directory, Running을 거쳐 Completed, Failed 또는 Canceled로 이동합니다. 트레이스 이벤트, 도구 호출, 최종 응답은 모두 Task로 돌아옵니다. 실행이 물리적으로 일어나는 곳은 Computer이고, 결과를 받아들이는 곳은 Task입니다.
동시성: Computer 하나가 얼마나 감당해야 할까?
각 Computer에는 작업 동시성 한도가 있고, 각 Agent에는 병렬 실행 Task에 대한 자체 최댓값이 있습니다. 기본값은 의도적으로 보수적입니다. Temporary 디렉터리를 사용하는 Agent는 Computer 한도의 50%가 기본값이고, Specified 디렉터리를 사용하는 Agent는 구성된 디렉터리 개수가 기본값입니다. 수동으로 그 개수보다 높은 값을 지정하면 쓰기가 충돌할 수 있다는 경고가 표시됩니다. 그 경고를 믿으세요.
문서의 권고를 따르는 것이 좋습니다. 동시성을 높이면 CPU, 메모리, 디스크, 제공자 용량, 리포지토리 대역폭을 더 많이 소비하므로, 현재 구성이 기존 워크로드를 안정적으로 처리한 뒤에만 올리세요. 사람들이 잊는 상한은 제공자 용량입니다. 하나의 모델 계정으로 10개의 실행을 병렬로 돌리면 속도 제한에 10배 빠르게 도달합니다. 확장 패턴은 여러 Claude Code 에이전트를 병렬로 실행하기에서 확인하세요.
온라인 상태의 Agent도 동시성이나 디렉터리 용량이 꽉 찼다는 이유만으로 대기 중인 작업을 가질 수 있습니다. Queued는 멈춘 상태가 아니라 건강한 상태입니다.
공유, 소유권, 그리고 호스트를 깨끗하게 유지하기
Computer가 팀 업무를 맡게 되면 세 가지 제어가 중요해집니다. Visibility는 누가 그것을 보고 사용할 수 있는지 결정합니다. Personal, Organization, Space 중 하나입니다. Ownership은 별개입니다. 소유자는 Computer를 이전할 수 있고, 삭제할 수 있는 유일한 사람입니다. 또한 로컬 개인 Computer의 경우 소유자가 어떤 Organization이 이를 사용할 수 있는지 통제하므로, 새 조직에 가입한다고 해서 노트북이 조용히 제공되는 일은 없습니다.
Agent 실행은 작업 디렉터리, 캐시, 아티팩트를 남기므로 정리 기능이 기본 제공됩니다. 기본적으로 완료되거나 취소된 실행을 약 7일 후 정리 대상으로 만들고, 최소 여유 공간 임계값을 강제할 수 있으며, 실행 중이거나 대기 중인 작업, 고정된 실행, 아직 조사 중인 실패한 실행은 절대 건드리지 않습니다. 즉시 확인하려면 sharkly daemon disk-usage가 사용량을 보고하고 sharkly daemon cleanup이 회수될 항목을 미리 보여 줍니다.
지금 가진 머신으로 시작하세요
Computer 개념은 호스팅 플랫폼이 여러분이 묻지 않기를 바라는 질문에 답합니다. 에이전트는 누구의 인프라 위에 있는가? 여기서 답은 여러분의 것입니다. 노트북 한 대부터 공유 서버 플릿까지요. 첫날부터 플릿이 필요하지는 않습니다. Computer 하나를 연결하고, Runtime 하나가 Available로 표시되는지 확인하고, Agent 하나를 만들고, 별것 아닌 일을 할당해 보세요. 노트북의 한계가 드러나면 그 옆에 서버를 등록하면 됩니다. Sharkly 문서에서 여기의 모든 설정을 더 자세히 다룹니다.
FAQ
Sharkly에서 Computer란 무엇인가요?
Computer는 Agent 작업을 위한 실행 호스트입니다. Agent가 필요로 하는 운영체제, 파일, 자격 증명, 네트워크 접근, 도구를 제공하는 연결된 기기, 서버 또는 컨테이너입니다. 작은 로컬 서비스가 이를 Sharkly에 연결하고, Runtime을 감지하고, 실행을 받아 진행 상황을 Task로 스트리밍합니다.
Sharkly가 자체 클라우드에서 내 코드를 실행하나요?
아니요. Agent 작업은 여러분이 연결한 Computer, 즉 여러분이 통제하는 머신에서 실행됩니다. Sharkly는 그 호스트들을 중심으로 할당, 큐잉, 진행 상황, 리뷰를 조율합니다. 모델 사용도 여러분의 몫입니다. 각 Computer에 설치된 코딩 도구에 구성된 구독이나 API 키를 통해 이루어집니다.
원격 서버를 Computer로 연결하려면 어떻게 하나요?
호스트에 Sharkly CLI를 설치하고, Computers 페이지에서 일회용 설치 토큰을 생성한 뒤, 해당 머신에서 sharkly computer register --install-token sit_...를 실행하세요. 토큰은 30분 후 만료되고 한 번만 작동하므로 이미지나 스크립트에 넣지 마세요. 그런 다음 원하는 에이전트 도구를 설치하고 인증한 뒤, 각 Runtime이 Available로 표시되는지 확인하세요.
Computer가 Online으로 표시되는데 실행이 시작되지 않는 이유는 무엇인가요?
Online은 로컬 서비스가 하트비트를 보내고 있다는 뜻일 뿐이며, 선택한 Runtime이 작업을 실행할 수 있다는 뜻은 아닙니다. Computer 상세 정보를 열고 Runtime의 기능 상태를 확인하세요. Needs configuration과 Not installed는 모두 실행을 막습니다. sharkly computer ping은 특정 Runtime이 왕복 통신을 완료하는지 확인해 줍니다.
