Paseo: Claude Code·Codex를 내 서버에서 돌리는 오픈소스 오케스트레이션 레이어

AI 코딩 에이전트 시대가 본격화되면서 Claude Code, Codex, Copilot 같은 도구를 자체 서버에서 운영하려는 수요가 빠르게 늘고 있다. Paseo는 이 요구에 정면으로 대응하는 오픈소스 셀프 호스팅 플랫폼으로, API 비용 절감과 데이터 프라이버시를 동시에 노리는 아키텍처로 2026년 GitHub 8,100스타를 돌파하며 개발자 커뮤니티의 주목을 받고 있다. 단순한 프록시 래퍼가 아니라 다중 에이전트 오케스트레이션·워크트리 격리·크로스 디바이스 접근을 하나의 로컬 데몬으로 통합한 구조가 핵심이다.

코딩 에이전트를 위한 운영 레이어

Paseo는 "자신의 하드웨어에서 AI 코딩 에이전트를 실행하고 어디서든 조종할 수 있게 해주는 오픈소스 플랫폼"으로 정의된다. 기존에 각 에이전트 CLI(Claude Code, Codex, GitHub Copilot, OpenCode, Pi 등)를 개별적으로 실행하던 방식을 통합 데몬 하나로 추상화한다.

지원 에이전트는 30개 이상이며, 주요 목록은 다음과 같다.

에이전트	제공사	실행 방식
Claude Code	Anthropic	네이티브 CLI 서브프로세스
Codex CLI	OpenAI	네이티브 CLI 서브프로세스
GitHub Copilot	Microsoft	네이티브 CLI 서브프로세스
OpenCode	오픈소스	네이티브 CLI 서브프로세스
Pi / OMP	Inflection AI	네이티브 CLI 서브프로세스

각 에이전트는 Paseo가 수정하거나 개입하지 않고 네이티브 CLI를 그대로 서브프로세스로 실행한다. API 토큰은 에이전트 프로세스 내부에만 존재하며 Paseo가 추출하거나 중계하지 않는다는 것이 보안 경계를 단순하게 유지하는 근거다. 라이선스는 AGPL-3.0으로, 소스를 수정해 서비스를 제공할 때는 소스 공개 의무가 따르지만 내부 운영용으로는 사실상 자유롭게 쓸 수 있다.

로컬 데몬을 중심에 둔 삼중 구조

Paseo의 아키텍처는 크게 세 레이어로 나뉜다.

⤢✕

로컬 데몬은 Paseo의 심장부다. 모든 클라이언트(데스크톱, 모바일, 웹, CLI)가 접속하는 단일 통신 엔드포인트인 WebSocket API 서버, Model Context Protocol을 통해 에이전트에게 추가 도구를 제공하는 MCP 서버, 여러 에이전트를 병렬 실행하고 워크트리별로 격리하는 에이전트 오케스트레이터, 이 세 역할을 동시에 수행한다.

클라이언트 레이어는 단일 데몬에 여러 클라이언트가 접속하는 구조다. Electron 기반 데스크톱 앱, Expo 기반 iOS·Android 네이티브 앱, 웹 인터페이스, CLI가 모두 동일한 WebSocket API로 데몬과 통신하기 때문에 책상에서 시작한 작업을 스마트폰으로 이어받는 시나리오가 가능해진다.

에이전트 서브프로세스 레이어에서는 각 에이전트가 데몬이 spawn()한 독립 프로세스로 실행된다. Claude Code라면 claude CLI, Codex라면 codex CLI가 그대로 실행되며, Paseo는 표준 입출력과 파일시스템만 조율할 뿐 에이전트 내부 로직이나 API 통신 경로에는 관여하지 않는다.

설치부터 데몬 구동까지

헤드리스 서버라면 CLI로 설치한다.

# Node.js 환경에서 전역 설치
npm install -g @getpaseo/cli

# 데몬 시작
paseo

# 백그라운드 데몬 모드
paseo --daemon

macOS, Windows, Linux용 데스크톱 앱 설치 파일을 공식 사이트에서 내려받아 실행하면 데몬이 자동으로 시작된다. 다만 최소한 하나의 에이전트 CLI가 미리 설치되어 있어야 한다.

# Claude Code 설치 예시
npm install -g @anthropic-ai/claude-code

# Codex CLI 설치 예시
npm install -g @openai/codex

# 설치 확인
which claude   # /usr/local/bin/claude
which codex    # /usr/local/bin/codex

에이전트 자격 증명(API 키 또는 구독 로그인)은 각 CLI가 자체적으로 관리하며, Paseo는 이 자격 증명에 접근하지 않는다.

원격 접근 연결 방식

로컬에서만 쓴다면 데몬을 시작하는 것으로 충분하다. 모바일이나 원격 근무 환경에서 접근이 필요하다면 세 가지 방식 중 고른다. 같은 네트워크 안에서 IP로 직접 접속하는 직접 연결(LAN)은 추가 설정 없이 가장 단순하다. Paseo가 운영하는 릴레이 서버를 거치되 트래픽이 종단 간 암호화돼 Paseo 서버조차 내용을 볼 수 없는 E2E 암호화 릴레이는 설정이 간단하고 방화벽 문제를 우회할 수 있다. 완전한 데이터 독립성이 필요한 기업 환경이라면 Tailscale, Cloudflare Tunnel, 또는 자체 Nginx 역방향 프록시를 쓰는 커스텀 터널을 권장한다.

# Nginx WebSocket 프록시 예시
server {
    listen 443 ssl;
    server_name paseo.example.com;

    ssl_certificate /etc/letsencrypt/live/paseo.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paseo.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7890;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

자체 릴레이 구성은 환경 변수로 지정한다.

PASEO_RELAY_ENDPOINT=127.0.0.1:8080
PASEO_RELAY_PUBLIC_ENDPOINT=relay.example.com:443
PASEO_RELAY_USE_TLS=true

워크트리 격리: 병렬 에이전트의 핵심

Paseo에서 가장 실용적인 기능 중 하나가 워크트리 기반 에이전트 격리다. 여러 에이전트가 동시에 작업할 때 브랜치 충돌 없이 각자의 작업 공간을 갖는다.

# 에이전트 A: fix-auth 브랜치에서 인증 버그 수정
paseo run --provider claude --worktree fix-auth "Fix JWT expiry handling"
# → 미리보기 URL: web.fix-auth.my-app.localhost

# 에이전트 B: add-dashboard 브랜치에서 새 기능 개발
paseo run --provider codex --worktree add-dashboard "Build analytics dashboard"
# → 미리보기 URL: web.add-dashboard.my-app.localhost

각 워크트리는 독립적인 git worktree로 생성되며, 브랜치 이름을 기반으로 한 고유 로컬호스트 URL이 자동 할당된다. 포트 충돌 없이 여러 프리뷰 서버를 동시에 운영할 수 있는 이유다.

에이전트 간 협업을 위한 내장 스킬(슬래시 커맨드)도 제공된다. 작업을 다른 에이전트에게 이전하는 /paseo-handoff, 수락 기준을 달성할 때까지 반복 실행하는 /paseo-loop, 단일 에이전트에게 자문을 구하는 /paseo-advisor, 여러 에이전트가 함께 분석·계획을 세우는 /paseo-committee가 있다. /paseo-committee는 동일한 문제를 Claude Code·Codex·OpenCode 같은 여러 에이전트가 독립적으로 분석하고 결과를 종합하는 패턴으로, 비용 대비 분석 품질을 높이는 데 쓰인다.

코드가 Paseo를 거치지 않는 구조

Paseo의 프라이버시 설계는 단순하다. 코드는 에이전트 프로세스 내에서만 처리되고 Paseo 레이어를 통과하지 않는다.

[로컬 코드베이스]
       ↓ (read/write)
[에이전트 프로세스] ←──→ [공급사 API: Anthropic / OpenAI]
       ↑
[Paseo 데몬]
(제어 신호만 전달)

Paseo 데몬은 에이전트에게 명령(태스크 시작·중지·프롬프트 전달)을 보내는 제어 채널만 담당한다. 실제 코드 컨텍스트·API 요청·응답 스트림은 에이전트 프로세스와 공급사 API 사이를 직접 흐른다. 음성 처리도 완전 로컬이다. 내장 STT(음성→텍스트)와 TTS(텍스트→음성)는 온디바이스에서 실행되고, OpenAI Speech API를 선택적으로 켤 수는 있지만 기본값은 로컬이다. 텔레메트리·강제 로그인·사용 데이터 수집은 없으며, 앱에서 할 수 있는 모든 작업은 터미널에서도 동일하게 수행할 수 있다.

이 구조는 Nginx로 WebSocket 업그레이드와 TLS 종단을 처리하는 역방향 프록시, git worktree로 컨테이너 없이도 작업 공간을 논리적으로 격리하는 프로세스 격리, Paseo가 자격 증명을 보유하지 않고 에이전트 프로세스에 위임하는 인증 위임(최소 권한 원칙), 텔레메트리가 없는 만큼 내부 로그 시스템을 별도로 구축해야 하는 감사 가능성이라는 네 가지 운영·보안 개념을 실제로 구현한 사례이기도 하다.

클라우드 직접 연결과 무엇이 다른가

셀프 호스팅 도입 여부는 팀 규모·보안 요구사항·운영 역량에 따라 달라진다.

⤢✕

Paseo 자체는 무료다. 비용은 각 에이전트 공급사 구독료(Claude Pro, Codex 크레딧 등)만 발생하며, 이는 클라우드 기반 AI 에이전트 관리 플랫폼들이 월 수십~수백 달러의 좌석 요금을 부과하는 것과 대비된다. 다만 오케스트레이션 레이어의 무료화가 전체 AI 비용 절감을 의미하지는 않는다. LLM API 호출 비용은 여전히 각 공급사에게 지불하며, 절감 효과는 "관리 플랫폼 비용 제거"와 "에이전트 재사용으로 인한 불필요한 세션 감소"에서 발생한다.

보안 트레이드오프도 항목별로 갈린다.

항목	클라우드 직접 연결	Paseo 셀프 호스팅
인증 관리	공급사 OAuth/API 키	공급사 CLI 자체 관리
코드 전송 경로	클라우드 거쳐 API	로컬 → API 직접
원격 접근 보안	공급사 SSO	Nginx TLS + Tailscale 등
감사 로그	공급사 대시보드	자체 구현 필요
취약점 책임	공급사	자체 팀

GDPR·HIPAA·금융 규제가 적용되는 환경에서 Paseo의 로컬 실행 아키텍처는 "데이터가 VPC를 벗어나지 않는다"는 조건을 충족시키는 실질적인 수단이 된다.

셀프 호스팅이 맞는 경우, 아닌 경우

2026년 기준으로 엔지니어링 팀의 61%가 AI 에이전트를 프로덕션 워크플로우에 통합하고 있다. 이 흐름 속에서 셀프 호스팅 판단 기준도 점점 명확해지고 있다.

의료·금융·국방처럼 데이터 외부 전송이 법적으로 제한된 환경, 소스 코드 기밀성이 최우선인 기업, 하루 1억 토큰 이상의 고용량 사용으로 API 단가 협상이 필요한 경우, 에이전트 스킬 추가나 UI 수정 같은 오픈소스 커스터마이징이 필요한 경우라면 셀프 호스팅이 합리적인 선택이다. 반대로 운영 부담이 이익을 초과하는 소규모 팀, 규제 요건이 없는 일반 SaaS 개발 환경, 빠른 실험과 프로토타이핑이 우선인 상황이라면 클라우드 직접 연결이 더 적합하다.

Paseo의 AGPL-3.0 라이선스와 오픈소스 생태계는 커스터마이징 가능성을 열어두면서도 커뮤니티 기여로 지속 발전하는 구조를 형성한다. PyTorch Korea 등 한국 기술 커뮤니티에서도 주목받기 시작한 이유다.

Paseo는 AI 코딩 에이전트 오케스트레이션을 클라우드 플랫폼 의존 없이 자체 인프라에서 운영할 수 있게 해주는 오픈소스 솔루션이다. 로컬 데몬 중심의 클라이언트-서버 아키텍처, git 워크트리 격리, 30개 이상 에이전트 지원, 텔레메트리 없는 프라이버시 설계가 핵심 차별점이다. 보안 규제 환경이나 코드 기밀성이 중요한 팀에게 실질적인 대안을 제공하며, API 비용 절감보다는 데이터 거버넌스 통제권을 확보하는 측면에서 더 큰 가치를 발휘한다.