Paseo 원격 개발: 데몬의 역할부터 연결·실행 환경 점검까지

Paseo 원격 개발은 개발 머신에서 돌아가는 데몬에 데스크톱·모바일·웹·CLI 클라이언트가 접속하는 구조입니다. 휴대폰은 작업을 요청하고 결과를 확인하는 역할을 맡고, 코딩 에이전트와 개발 도구는 데몬이 있는 컴퓨터나 서버에서 실행돼요. 데몬은 클라이언트의 요청을 받아 작업을 관리하는 상주 프로그램이라고 보면 됩니다.

그래서 연결 방법을 고르기 전에 '접속하는 기기'와 '코드를 실행하는 머신'부터 나눠 두길 권합니다. 이 구분이 서야 에이전트 CLI를 어디에 설치하고 작업할 저장소를 어디에 준비할지가 분명해지거든요.

데몬과 에이전트 CLI는 하는 일이 다릅니다

요청은 클라이언트 → 연결 경로 → 데몬 → 에이전트 프로세스 순서로 흘러갑니다. 클라이언트가 명령을 보내면 데몬은 설치·인증된 외부 에이전트 CLI를 하위 프로세스로 실행하고 관리해요. 실제로 코드를 고치거나 테스트를 돌리는 쪽은 이 에이전트입니다. 데몬에 잘 연결됐다고 해서 에이전트까지 정상적으로 실행된다고 볼 수는 없으니, 두 가지는 따로 확인하는 게 맞아요.

프로바이더라는 말도 자주 보게 됩니다. 에이전트 CLI의 실행 방식과 입출력을 연결하는 인터페이스로, CLI를 시작하는 방법과 출력 전달, 사용자 입력 처리를 이어 주는 역할을 해요.

가장 헷갈리기 쉬운 건 경로입니다. 예를 들어 원격 저장소에서 테스트를 요청하면서 --cwd /workspace를 지정했다면, 이 /workspace는 개발 머신의 작업 디렉터리를 가리켜요. 지금 접속한 기기의 폴더로 생각하면 경로 문제를 엉뚱한 곳에서 찾기 쉽습니다.

실행 머신부터 준비하고, 연결 방식은 그다음에

순서는 개발 머신이 먼저예요. 사용할 에이전트 CLI를 설치하고 인증한 뒤 Paseo 데몬을 실행하세요. 데스크톱 앱은 포함된 데몬을 자동으로 시작해 주고, 화면 없는 서버라면 npm install -g @getpaseo/cli로 설치한 다음 paseo를 실행하면 됩니다. 공식 Docker 이미지에도 에이전트 CLI는 들어 있지 않으니, CLI와 인증 정보는 따로 준비해야 해요.

실행 환경이 갖춰졌다면 접속할 기기에 맞춰 연결 경로를 고르면 됩니다.

신규 설치에서는 릴레이가 꺼져 있어서 paseo daemon pair 등으로 활성화하고 페어링해야 합니다. 데몬이 릴레이로 외부 연결을 만드는 방식이라 공유기 포트 포워딩 없이도 접속할 수 있어요.

SSH는 이미 실행 중인 원격 데몬에 접속하는 기능입니다. 원격 Paseo를 설치하거나 시작하는 일까지 처리해 주지는 않으니, 서버 준비를 먼저 끝내 두세요. 포트도 혼동하기 쉬운 지점이에요. ssh://user@host:2222에서 2222는 SSH 서버 포트이고, 데몬 포트는 daemonPort로 별도 지정합니다. 둘을 섞으면 SSH 접속은 되는데 데몬 연결에서 막힐 수 있으니, 설정할 때 공식 연결 문서를 함께 확인하세요.

접속은 되는데 작업이 안 돌 때

점검은 '데몬 도달 여부 → 대상 호스트·작업 경로 → 프로바이더 경로·버전' 순서로 하길 권합니다. 접속 대상과 저장소 위치가 맞아야 실행 파일을 진단하는 것도 의미가 생기기 때문이에요.

터미널에서만 에이전트가 실행된다면 데몬의 PATH가 다를 수 있습니다. paseo provider diagnostic <provider>로 실행 파일 경로와 데몬의 PATH, 버전을 확인해 보세요. 각 항목이 무슨 뜻인지는 공식 문제 해결 문서에서 볼 수 있어요.

설정 파일을 고친 뒤에는 paseo reload를 실행합니다. 수신 주소나 인증처럼 재시작이 필요한 항목은 paseo daemon restart로 반영해야 해요. 데몬을 재시작하는 동안 작업이 이어진다는 안내가 있는데, 이를 호스트 재부팅까지 넓혀 해석하면 안 됩니다.

보안에서 섞어 생각하기 쉬운 부분도 짚어 둘게요. 비밀번호 인증은 접근 통제이고, 전송 암호화와는 별개입니다. 릴레이 통신은 종단 간 암호화되지만 IP 주소·통신 시점·메시지 크기·세션 ID는 릴레이에 보여요. 페어링 QR 코드와 링크도 공개하지 마세요.

이 내용은 2026-11-07을 기준으로 공식 문서와 저장소 main의 범위에서 정리했습니다. 사용하는 릴리스의 지원 여부와 동작은 해당 버전의 공식 안내에서 확인하세요.