pi-dispatch

코딩 에이전트가 당신의 감시 없이, 놀라게 하는 비용 지불이나 기계에 대한 접근 권한을 주지 않고도 저장소에서 작업하게 하세요.

pi는 일반적으로 터미널에서 실행하는 오픈 소스 코딩 에이전트입니다. pi-dispatch는 이를 사용자의 자체 기기나 서버에서 백그라운드 서비스로 실행합니다. 작업은 스케줄에 따라, 명령줄에서, 또는 포지(forge: GitHub, GitLab, Forgejo 또는 Azure DevOps)로부터 이슈, 댓글 또는 풀 리퀘스트가 도착할 때 시작됩니다. 각 작업은 자신만의 격리된 컨테이너를 할당받습니다. 에이전트는 그 안에서 하나의 작업을 수행하고, pi-dispatch는 그것이 무엇을 했고 얼마의 비용이 들었는지 기록하며, 컨테이너는 폐기됩니다.

pi에는 작업 큐(job queue), 동시성 제어(concurrency control), 지출 한도(spend limit)가 없으며, 자체 README에 따르면 권한 시스템(permission system)도 없습니다. pi-dispatch는 바로 그 계층만을 추가하고 다른 것은 아무것도 추가하지 않습니다. 이는 사용자가 이미 사용하는 에이전트와 비교할 또 다른 에이전트가 아닙니다. 이것은 이미 실행 중인 pi 주변의 큐, 예산 및 상자이며, 저장소가 이미 가지고 있는 .pi/ 설정을 통해 제어됩니다.

얻게 되는 것:

• 모든 작업을 감싸는 컨테이너. 각 작업은 root 권한 없이 실행되며, 모든 Linux capability가 제거된 컨테이너에서 실행되고, 이후 삭제됩니다. 여기에 지침(instructions)이 읽기 전용으로 마운트됩니다. 이 컨테이너가 pi의 누락된 권한 시스템입니다. Docker 또는 Podman(docs/backends.md)에서 실행됩니다.

• 지출 전에 적용되는 한도. 작업당 턴 제한, 전체 배포에 대한 작업 및 토큰 상한선, 그리고 일별, 주별, 월별 달러 상한선이 있습니다. 각 작업은 자체적인 달러 상한선을 가질 수도 있습니다. 이 경우 해당 상한을 초과할 수 있는 모델 호출이 발생하기 전에 작업이 중지됩니다. 상한선은 리포(repo), 폴더, 모델 또는 프로젝트별로도 적용될 수 있습니다. 상한을 초과하는 작업은 컨테이너가 시작되기 전에 거부됩니다. 이후 인사이트 페이지에서는 흐름(flow), 트리거(trigger), 모델, 리포, 프로젝트 및 일별 지출액을 보여줍니다(docs/costs.md).

• 프로젝트와 예산 분할. 리포와 폴더를 프로젝트로 그룹화하고 각 프로젝트에 상한선을 설정합니다. 일별, 주별 또는 월별 총 달러 금액을 설정하고, 프로젝트당 하한선(floor)을 지정할 수 있습니다. 포트폴리오 관리자 흐름(portfolio manager flow)은 키 입력 없이 내부 프로젝트 간에 자금을 이동시킬 수 있습니다. 모든 이동은 기록되며 되돌릴 수 있습니다(docs/projects.md, docs/allocation.md).

• 프로젝트당 크기, 머신별 예산. 각 프로젝트의 작업은 해당 행(row)이 설정한 메모리와 CPU를 할당받습니다 (기본값 4 GB 및 2 CPUs). 작업은 그 크기가 해당 머신에서 이미 실행 중인 것 옆에 들어갈 공간과, 대기하는 큰 작업을 위한 여유 공간을 확보할 때만 시작하며, 이로 인해 작은 작업의 흐름이 이를 고갈시키지 못하게 합니다. pi-dispatch doctor와 패널은 사용된 실행 기록을 바탕으로 크기를 제안하고, 사용자가 이를 적용합니다(docs/sizing.md).

• 모델 허용 목록(Model allow lists). 트리거의 run.models, 또는 전체 배포에 대한 PI_ALLOWED_MODELS는 작업이 사용할 수 있는 모델 이름을 지정합니다. 작업은 다른 모델을 호출하기 전에 중지됩니다(docs/triggers.md).

• 사용자가 제어하는 이미지. job 이미지는 git, gh, Playwright 및 Chromium을 포함하므로, job이 프론트엔드를 빌드하고 확인할 수 있습니다. image/Dockerfile에서 자체 툴체인을 추가하거나, 트리거가 자체 이미지를 사용하도록 할 수 있습니다(docs/job-image.md).

• 세 가지 방식으로 진입, 하나의 경로. CLI 명령어, cron 스케줄 또는 forge 이벤트 모두 동일한 큐(queue), 동일한 컨테이너 및 동일한 패널(Triggers)을 사용합니다.

• 사용자 저장소가 에이전트를 안내함 pi의 자체 .pi/ 폴더를 통해: 스킬(agent가 따르는 Markdown 지침 파일)과 페르소나. 이들 아래에는 agent가 제거할 수 없는 작은 안전 장치(safety floor)가 있습니다.

사용 시점

작업이 반복적이거나 이벤트 기반이며, 사용자가 개입하지 않고 실행되기를 원할 때 pi-dispatch를 사용하세요:

• 새로운 이슈를 분류하거나, 보고서를 업데이트하거나, 백로그를 정리하는 야간 job;
• 작은 일상적인 수정의 경우,

개별 장치에서 일회성 세션을 진행하는 경우, 일반 pi만으로 충분합니다. pi-dispatch는 터미널을 아무도 지켜보지 않는 동안 실행되는 에이전트를 위한 것입니다. 두 가지 뷰가 구축한 것을 조정하는 데 도움을 줍니다: **그래프(graph)**는 어떤 트리거가 어떤 플로우를 시작하는지(작업이 실행되는 스킬은 플로우를 참조) 그리고 무엇이 무엇에 연결되었는지(docs/graph.md)를 보여주며, **인사이트(insights)**는 각각의 비용, 구독료가 효과적인지 여부, 각 장치가 얼마나 바빴는지를 보여줍니다(docs/insights.md). /dispatch insights는 이 두 가지 정보를 모두 디스크에서 브라우저가 열 수 있는 단일 파일로 작성합니다:

빠른 시작(Quickstart)

필요한 것:

• Docker 또는 Podman(Docker API를 통해 rootful 하거나, Linux에서 PI_BACKENDS=podman을 사용하여 rootless로 실행할 수 있습니다. 어떤 것을 선택할지: Docker 또는 Podman);
• Node 22.19 이상;
• 작업 내에서 pi가 사용하는 모델 제공업체용 API 키(제공업체 및 모델에 대한 자세한 내용은 Providers and models를 참조);
• 항상 컨테이너 런타임을 실행할 수 있는 장치(어디서 실행할 수 있는지: Where it can run).

pi에서 (기본 경로)

이미 pi를 사용하고 있다면, 콘솔이 모든 것을 설정하도록 하세요:

pi install npm:@edgehero/pi-dispatch-admin   # 그런 다음, pi 내부에서: /dispatch

아무것도 구성되지 않은 상태에서 /dispatch는 안내된 설정을 시작합니다. 배포 폴더를 생성하고, 콘솔이 예상하는 정확한 pi-dispatch 버전을 설치하며, 아래에 표시된 것과 동일한 up 과정을 실행하고, 워커(worker)를 서비스로, 포지(forge) 이벤트의 수신기로 설치할 수 있습니다. 이는 관리자 패널에서 끝나며, 현재 위치한 리포지토리용 선택적 첫 번째 트리거가 제공됩니다. 모든 단계는 무엇을 할 것인지 말해주고 먼저 묻습니다. 리포지토리에 아무것도 쓰여지지 않으며, 어떤 자격 증명도 대화 상자를 통해 전달되지 않습니다.

서버 및 헤드리스(Servers and headless)

일반 명령어와 동일한 설정입니다. 클론이 필요하지 않습니다:

mkdir my-dispatch && cd my-dispatch
npx @edgehero/pi-dispatch up      # one pass, asks before every container action
#  edit .env and set your provider key (leave it blank if pi already holds your API key)
...

up은 작업(job) 이미지를 가져와 Valkey(큐의 데이터베이스)를 자체 비밀번호로 시작하므로, 호스트의 다른 계정에서는 큐를 읽을 수 없습니다. 또한, 작업이 네트워크에 접근하는 출구 프록시(egress proxy)를 시작합니다. 이 명령어는 설정 파일들을 작성하고(init만 그 부분만 수행함), 아직 값이 없는 .env 라인들을 프롬프트 없이, 그리고 절대 덮어쓰지 않으면서 채웁니다. 그런 다음 doctor 사전 점검을 실행합니다:

로컬 작업은 폴더를 제자리에서 수정하며, 되돌릴 수 없습니다. pi-dispatch run은 커밋되지 않은 변경 사항이 있는 폴더는 --force 옵션을 전달하지 않는 한 거부합니다. 해당 폴더는 최소 하나의 커밋이 있는 git 저장소의 루트여야 하며, run은 어떤 다른 폴더도 큐에 넣기 전에 거부합니다. 크론 트리거의 폴더는 실행될 때 확인되지 않으므로, 해당 폴더는 직접 커밋 상태를 유지해야 합니다.

이 리포지토리를 복제(git clone, npm ci, 그리고 npx pi-dispatch init, doctor, worker)하는 것은 사용자 정의 작업 이미지를 빌드할 때만 필요합니다. 작업은 --pull=never로 시작하므로, 모든 이미지를 먼저 가져오거나(pull) 빌드해야 합니다. 호스트가 가지고 있지 않은 이미지를 이름으로 지정한 작업은 비용이 발생하기 전에 거부됩니다.

이름 지정 주의사항. 게시된 패키지들은 스코프되어 있습니다: @edgehero/pi-dispatch (pi-dispatch 명령어). 순수한 npm 이름인 pi-dispatch는 관련 없는 패키지에 속하므로(참조 License), 체크아웃 외부에서는 항상 스코프 이름을 사용해야 합니다.

실행 가능한 위치

pi-dispatch는 컨테이너를 시작하는 장시간 실행 워커이므로, 다음 두 가지 작업을 모두 수행할 수 있는 머신에서 실행되어야 합니다: Node 22.19 이상 버전과 컨테이너 런타임(Docker 또는 Podman)이 동일한 호스트에 설치된 환경.

Docker 또는 Podman

Job은 두 가지 백엔드 중 하나에서 실행되며, 둘 다 워커 자체 호스트에서 작동합니다:

• local, 기본값: Docker 데몬(또는 그 Docker API를 통한 rootful Podman). 설정하기 가장 쉽고, macOS와 Windows에서는 유일한 선택지입니다. 워커는 데몬의 소켓에 접근해야 하며, 이 접근은 호스트에서 root 권한과 동등합니다.
• podman: Linux 환경에서 워커 자체 계정으로 실행되는 rootless Podman입니다. 루트로 실행되는 데몬이 없으며, 워커가 root와 동등한 그룹을 필요로 하지 않습니다. 각 Job은 해당 계정의 컨테이너 스토어 내에서 워커 자체 uid로 실행되므로, 컨테이너 이스케이프(container escape)는 특권 없는 계정에 도달합니다. Valkey, egress 프록시 및 워커는 systemd 사용자 유닛으로 실행됩니다. 공유 환경 또는 보안에 민감한 Linux 서버를 위해 이것을 선택하세요.

rootless Podman을 사용하려면: 일반 계정(root가 아닌)으로 워커를 실행하고 자체적인 하위 ID를 부여하며, 로그인 없이 서비스가 실행되도록 linger 기능을 활성화합니다(sudo loginctl enable-linger <account>), .env에 PI_BACKENDS=podman을 설정하고, podman으로 Job 이미지를 가져온 다음, pi-dispatch up, pi-dispatch service install, 그리고 pi-dispatch doctor --live를 실행합니다. 전체 측정 설정과 거부되는 경우(macOS 및 Windows의 Podman 머신, 이 환경에서의 rootful 또는 원격 Podman, root 워커)는 docs/podman.md에 나와 있습니다.

Provider와 모델

pi-dispatch 자체는 AI 키가 필요하지 않습니다. 큐(queue), 캡(caps), 컨테이너, 그리고 패널은 모델을 실행하지 않습니다. 키는 각 작업 내부에서 실행되는 에이전트인 pi를 위한 것이며, 워커가 이를 각 작업 컨테이너에 전달합니다. pi-dispatch는 pi가 지원하는 대부분의 프로바이더와 함께 작동합니다: Anthropic, OpenAI, Google, Groq 및 약 30개 이상의 다른 프로바이더(예외 사항은 아래 참조). .env에서 기본값을 선택하세요:

PI_PROVIDER=anthropic
PI_MODEL=claude-sonnet-5-5 # 비용 예측 가능성을 위해 정확한 모델 버전을 유지하는 것이 좋습니다
ANTHROPIC_API_KEY=...